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 global. Berikut detailnya:

100 request per menit per akun

Berlaku untuk semua antarmuka — REST API, GraphQL API, dan MCP Server

Contoh Response 429

Jika rate limit terlampaui, API mengembalikan response berikut dengan field retryAfter yang menunjukkan waktu tunggu dalam detik:

{
  "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
  }
}

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": 45
  }
}

Kode Error

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

HTTP Status	Error Code	Deskripsi
400	BAD_REQUEST	Parameter query tidak valid atau request salah format
401	AUTHENTICATION_REQUIRED	Autentikasi diperlukan — sertakan header Authorization: Bearer
401	INVALID_API_KEY	API key tidak valid atau sudah dicabut
402	INSUFFICIENT_CREDITS	Kredit habis — perlu top up untuk melanjutkan
404	NOT_FOUND	Resource yang diminta tidak ditemukan
422	VALIDATION_ERROR	Validasi input gagal
429	RATE_LIMIT_EXCEEDED	Terlalu banyak request — coba lagi nanti
500	INTERNAL_ERROR	Kesalahan server tak terduga

Contoh Error Response

Berikut adalah contoh response untuk setiap jenis error:

400

BAD_REQUEST

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

401

AUTHENTICATION_REQUIRED

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

401

INVALID_API_KEY

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

402

INSUFFICIENT_CREDITS

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

404

NOT_FOUND

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

422

VALIDATION_ERROR

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

429

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": 45
  }
}

500

INTERNAL_ERROR

{
  "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:

1. Gunakan Exponential Backoff

Saat menerima error 429 atau 500, jangan langsung mencoba lagi. Gunakan exponential backoff — tunggu dengan durasi yang meningkat secara eksponensial di setiap percobaan ulang.

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');
}

2. Periksa retryAfter pada Error

Saat menerima error 429, response body mengandung field error.retryAfter yang menunjukkan waktu tunggu dalam detik. Gunakan nilai ini untuk menentukan kapan harus mencoba lagi.

3. Tangani Error Spesifik

Jangan hanya memeriksa HTTP status code — periksa juga error.code dalam response body untuk menentukan tindakan yang tepat. Misalnya, INSUFFICIENT_CREDITS memerlukan top up, sementara RATE_LIMIT_EXCEEDED hanya memerlukan tunggu.

4. Cache Response

Data kode pos relatif statis — cache response API di sisi klien untuk mengurangi jumlah request yang tidak perlu. Pertimbangkan menggunakan cache dengan TTL 24 jam untuk data yang jarang berubah.

Jika Anda memerlukan rate limit yang lebih tinggi, silakan hubungi admin untuk penyesuaian.