Rate Limit & Error

Pelajari tentang rate limiting, kode error, dan praktik terbaik untuk menangani error pada Kode Pos API.

Rate Limiting

Untuk menjaga stabilitas layanan, Kode Pos API menerapkan rate limit berbasis mode akun (Sandbox dan Production). Batas dihitung per menit per akun.

Batas per Mode

Mode akun ditentukan oleh riwayat pembelian kredit. Akun baru beroperasi di mode Sandbox dan naik otomatis ke mode Production setelah pembelian kredit berbayar pertama.

Contoh Response 429

Jika rate limit terlampaui, API mengembalikan response berikut dengan field retryAfter yang menunjukkan waktu tunggu dalam detik (karena window rate limit adalah 1 menit):

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retryAfter": 60
  }
}

Ketika Rate Limit Terlampaui

Jika Anda melebihi batas rate limit, API akan mengembalikan HTTP status 429 dengan error code RATE_LIMIT_EXCEEDED:

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retryAfter": 60
  }
}

Kode Error

Berikut adalah daftar lengkap kode error yang mungkin dikembalikan oleh API:

Contoh Error Response

Berikut adalah contoh response untuk setiap jenis error:

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid query parameter: first must be a positive integer"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication is required. Include Authorization: Bearer header."
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked."
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You have run out of credits. Please top up to continue using the API."
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: q must be at least 2 characters"
  }
}

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retryAfter": 45
  }
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later."
  }
}

Praktik Terbaik

Untuk menangani error dengan efektif, ikuti praktik terbaik berikut:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const data = await response.json();
      const retryAfter = data.error?.retryAfter || 60;
      const delay = Math.min(retryAfter * 1000, Math.pow(2, attempt) * 1000);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}