Batas permintaan

Setiap kunci API punya batas jumlah permintaan per 60 detik. Batas ini menjaga API tetap cepat untuk semua pengguna. Integrasi yang membaca header batas dan menunggu saat diminta tidak akan terganggu.

Batas yang berlaku

Batas	Nilai	Berlaku untuk
Umum	120 permintaan per 60 detik per kunci	Semua endpoint
Tulis	30 permintaan per 60 detik per kunci	POST /v1/shipments dan POST /v1/shipments/{id}/cancel, di samping batas umum
Ukuran body	64 KB	Semua POST

Setiap kunci punya hitungan sendiri, termasuk kunci lain di workspace yang sama.

Tab Log API di menu Developer mencatat paling banyak 60 permintaan per kunci per 60 detik, ditambah penolakan 429 pertama di jendela itu. Permintaan di atas jumlah itu tetap diproses, hanya tidak dicatat di Log API. Simpan header X-Request-Id di log servermu bila butuh catatan lengkap.

Selain batas permintaan, mode live punya batas akun: jumlah pengiriman per hari (429 daily_limit_reached) dan total biaya per pengiriman (422 amount_limit_exceeded). Batas ini berlaku untuk pengiriman dari aplikasi maupun API. Kalau batas ini menghambat usahamu, hubungi tim OngkirHub.

Header batas permintaan

Setiap respons untuk kunci yang valid membawa header berikut.

Header	Artinya
RateLimit-Limit	Batas permintaan dalam jendela saat ini.
RateLimit-Remaining	Sisa permintaan dalam jendela saat ini.
RateLimit-Reset	Detik sampai jendela berikutnya dimulai.
Retry-After	Hanya pada respons 429: detik sebelum boleh mencoba lagi.

Saat batas terlampaui

API menjawab 429 dengan kode rate_limited:

{
  "error": {
    "code": "rate_limited",
    "message": "Terlalu banyak permintaan. Tunggu sebentar, lalu coba lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": { "retryAfterSec": 21 }
  }
}

Tunggu selama Retry-After detik (sama dengan details.retryAfterSec), lalu kirim ulang permintaan yang sama. Untuk POST, pakai Idempotency-Key yang sama. Respons 429 tidak disimpan oleh Idempotency-Key, jadi aman diulang.

Percobaan berulang dengan kunci yang tidak valid juga dibatasi per alamat IP dan dijawab dengan 429 rate_limited. Periksa kuncimu bila ini terjadi.

Body terlalu besar

Body lebih dari 64 KB ditolak dengan 413 payload_too_large, dan details.maxBytes berisi batasnya (65536). Satu permintaan cek tarif atau pembuatan pengiriman bisa memuat sampai 50 item, yang biasanya jauh di bawah batas ini.

Tips agar tidak terkena batas

• Simpan hasil GET /v1/couriers dan GET /v1/locations di sistemmu. Datanya jarang berubah.
• Pakai webhook untuk perubahan status daripada memanggil GET /v1/shipments/{id} berulang kali.
• Saat membaca daftar panjang, pakai limit=100 supaya jumlah halaman lebih sedikit.
• Sebar pekerjaan massal, misalnya pembuatan banyak pengiriman, agar tidak melewati 30 permintaan tulis per 60 detik.
• Pantau RateLimit-Remaining dan beri jeda sebelum angkanya habis.