Error Codes

Format error standar untuk semua respons gagal:

{
  "error": "human readable message",
  "code":  "machine_readable_code"
}

4xx — Client Errors

Code	Deskripsi	Tindakan
`invalid_cursor`	Pagination cursor tidak valid atau sudah expired	Mulai dari halaman pertama (tanpa cursor)
`invalid_bank_code`	`bank_code` tidak ada di referensi	Cek kode bank yang valid dengan tim Kesles
`invalid_timestamp_format`	Format `X-Timestamp` bukan unix seconds	Gunakan `int64` unix timestamp
`missing_required_param`	Query param wajib tidak disertakan	Cek dokumentasi endpoint

Code	Deskripsi	Tindakan
`invalid_signature`	HMAC signature tidak cocok	Cek ulang string-to-sign dan secret
`timestamp_expired`	`X-Timestamp` lebih dari ±300 detik dari waktu server	Sinkronkan clock dengan NTP, regenerate timestamp
`api_key_not_found`	`X-API-Key-ID` tidak dikenal	Hubungi tim Kesles
`api_key_revoked`	Key sudah direvokasi	Hubungi tim Kesles untuk key baru
`api_key_expired`	Key sudah melewati `expires_at`	Lakukan key rotation

Code	Deskripsi	Tindakan
`ip_not_allowed`	IP caller tidak ada di allowlist	Hubungi tim Kesles untuk update IP allowlist
`tier_internal_required`	Endpoint tidak tersedia untuk PSP	Jangan panggil endpoint ini

Code	Deskripsi	Tindakan
`merchant_not_found`	Merchant tidak ada, tidak aktif, tidak punya NMID, atau milik bank lain	Verifikasi NMID; merchant mungkin belum aktif atau bukan milik bank kamu

Code	Deskripsi	Tindakan
`rate_limit_exceeded`	Melebihi rate limit per API key	Tunggu `Retry-After` header (dalam detik), lalu retry

Header yang disertakan pada 429:

Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716453000

HTTP	Code	Deskripsi	Tindakan
500	`internal_server_error`	Error tidak terduga di sisi Kesles	Retry dengan backoff; jika persisten, hubungi tim Kesles dengan `X-Request-ID`
502	`upstream_error`	Dependency internal Kesles tidak merespons	Retry dengan backoff
503	`service_unavailable`	Maintenance atau overload	Tunggu `Retry-After` jika ada, lalu retry

Retry Policy untuk 5xx

Implementasikan exponential backoff untuk semua 5xx:

Jangan retry 4xx (kecuali 429 dengan Retry-After).

Selalu sertakan X-Request-ID (uuid v4) di setiap request. Ketika melaporkan error ke tim Kesles, sertakan: