Batas & Kuota (Rate Limits)

Rate Limits & Quota

AgenWebsite Rate API menerapkan dua lapis pembatasan: kuota harian (jumlah request per hari) dan burst per menit (kecepatan request). Keduanya dihitung per pengguna — dibagi rata di semua API key milik Anda — dan 1 request dihitung 1, bukan per baris kurir.

Kuota harian per tier

Kuota di-reset setiap hari pukul 00:00 WIB (Asia/Jakarta, UTC+7). Tabel berikut merangkum setiap tier:

Header X-RateLimit-*

Setiap respons — sukses maupun error — menyertakan header berikut agar Anda dapat memantau sisa kuota tanpa memanggil /v1/usage:

Informasi yang sama juga tersedia dalam body pada blok rate_limit, dan bisa diminta kapan saja lewat GET /v1/usage:

GET /v1/usage

curl https://api.agenwebsite.com/v1/usage \
  -H "x-api-key: awk_live_xxxxxxxx"

# Response 200
{
  "plan": "pro",
  "limit": 30000,
  "used": 2,
  "remaining": 29998,
  "reset_at": "2026-07-03T00:00:00+07:00"
}

Respons 429 & Retry-After

Bila kuota harian habis atau batas burst per menit terlampaui, API membalas HTTP 429 Too Many Requests dengan kode rate_limit_exceeded. Respons menyertakan header Retry-After (dalam detik) yang memberi tahu kapan Anda boleh mencoba lagi, di samping header X-RateLimit-*.

Response 429

HTTP/1.1 429 Too Many Requests
Retry-After: 43
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-07-03T00:00:00+07:00

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Kuota permintaan Anda sudah habis. Coba lagi nanti atau upgrade paket.",
    "request_id": "req_9c3e11"
  }
}

Praktik terbaik

Agar integrasi Anda hemat kuota dan tahan terhadap limit:

• Hormati Retry-After. Saat menerima 429, tunggu sesuai nilai header sebelum mengulang — jangan langsung retry.
• Pakai exponential backoff untuk retry otomatis (mis. 1s, 2s, 4s) dengan sedikit jitter.
• Cache hasil ongkir di sisi Anda. Tarif untuk kombinasi asal-tujuan-berat yang sama relatif stabil; cache beberapa menit memangkas request drastis.
• Pantau X-RateLimit-Remaining dan beri notifikasi internal saat mendekati batas.
• Gabungkan kurir dalam satu request. Satu POST /v1/rates dengan beberapa couriers tetap dihitung 1 request — jauh lebih hemat daripada memanggil per kurir.
• Upgrade bila perlu. Toko volume tinggi sebaiknya naik ke Pro/Max; downgrade tidak pernah mencabut key Anda.