Errors & rate limit

Bentuk error, daftar kode, dan batas 60 request per menit.

Bentuk error

Semua error memakai bentuk yang sama:

json

{ "error": { "code": "BUDGET_EXCEEDED", "message": "Harga 2900000 melebihi batas 1000" } }

Pesan bisa berbahasa Indonesia atau Inggris dan bisa berubah. Buat logika berdasarkan code dan status HTTP, bukan message.

Code	HTTP	Arti
VALIDATION	400	Body bukan objek JSON, atau format Idempotency-Key salah
VALIDATION	422	Field wajib hilang atau nilainya tidak valid (pesan menyebut field-nya)
UNAUTHORIZED	401	API key tidak ada, salah format, salah, atau sudah dicabut
FORBIDDEN_SCOPE	403	Key tidak punya scope untuk endpoint ini
ACCOUNT_PENDING	403	Organisasi masih ditinjau. Endpoint baca tetap bisa dipakai
ACCOUNT_REJECTED	403	Organisasi ditolak atau ditangguhkan
NOT_FOUND	404	Route, order, kasus, atau penawaran tidak ada di organisasi kamu
SERVICE_NOT_FOUND	404	Kode layanan tidak ada, tidak aktif, atau tidak tersedia untuk agent
METHOD_NOT_ALLOWED	405	Path benar, method salah
INVALID_STATE	409	Aksi tidak boleh di status sekarang (mis. accept sebelum diserahkan)
BUDGET_EXCEEDED	402	Harga di atas max_budget atau batas per order key
MONTHLY_BUDGET_EXCEEDED	402	Order akan melewati batas bulanan key
INSUFFICIENT_DEPOSIT	402	Deposit organisasi kurang. Isi deposit lalu ulangi
SERVICE_IS_BID	422	Layanan berbasis penawaran. Ajukan sebagai kasus
NOT_AGENT_ELIGIBLE	422	Layanan belum dibuka untuk agent
INTAKE_INVALID	422	Field intake wajib belum diisi (daftar key ada di pesan)
IDEMPOTENCY_KEY_REUSED	422	Idempotency-Key sudah dipakai untuk body lain dalam 24 jam
STORY_TOO_SHORT	422	Cerita kasus kurang dari 30 karakter
EMAIL_INVALID	422	contact_email tidak valid
RATE_LIMITED	429	Lebih dari 60 request per menit untuk key ini
INTERNAL	500	Kesalahan di sisi kami. Aman di-retry (pakai Idempotency-Key untuk order)

60 request per menit per API key, jendela tetap 60 detik yang mulai dari request pertama.
Setiap respons yang lolos autentikasi membawa X-RateLimit-Limit: 60 dan X-RateLimit-Remaining.
Melewati batas: 429 RATE_LIMITED dengan header Retry-After (detik).
Request yang gagal di routing (404/405) atau autentikasi (401) tidak dihitung.

Catatan

Untuk memantau order, webhook jauh lebih hemat daripada polling. Kalau polling, jeda satu menit per order sudah cukup; SLA dihitung dalam hari.

Status	Retry?
429	Ya, setelah Retry-After
500, timeout, koneksi putus	Ya, dengan backoff. Untuk POST /v1/orders pakai Idempotency-Key yang sama
402	Setelah deposit diisi atau budget dinaikkan manusia
400, 401, 403, 404, 405, 409, 422	Tidak. Perbaiki request atau tunggu status berubah