Error

Bentuk error

Setiap respons error punya struktur yang sama:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amount must be at least 10000 for virtual_account"
  }
}

code bersifat stabil dan bisa dibaca mesin — tulis penanganan error Anda berdasarkan ini, bukan berdasarkan message atau status HTTP saja. message ditujukan untuk Anda sebagai developer (aman untuk di-log), bukan untuk ditampilkan ke pelanggan Anda.

Referensi status dan code

Status	Code	Arti
400	VALIDATION_ERROR	Body request valid secara bentuk tapi melanggar aturan bisnis (misal amount di bawah minimum metode)
400	INVALID_REQUEST	Body request bukan JSON valid, atau tidak sesuai bentuk yang diharapkan
400	IDEMPOTENCY_KEY_REQUIRED	Endpoint ini mensyaratkan header Idempotency-Key
401	UNAUTHORIZED	Header Authorization tidak ada, atau API key tidak valid/sudah di-revoke
403	FORBIDDEN	Key valid tapi tidak diizinkan melakukan operasi ini (misal beberapa read khusus dashboard tidak tersedia untuk API key)
403	PROJECT_UNAVAILABLE	Project ada tapi belum bisa dipakai sekarang (tidak aktif, atau di production dan belum disetujui)
403	CORS_ORIGIN_FORBIDDEN	Origin browser pada request tidak ada di daftar yang diizinkan project
404	PROJECT_NOT_FOUND	Project tidak ada, atau milik API key lain — lihat Autentikasi
404	RESOURCE_NOT_FOUND	Payment link, payment, atau resource lain yang diminta tidak ada
409	CONFLICT	Sudah ada resource dengan nilai unik yang sama
409	IDEMPOTENCY_CONFLICT	Idempotency-Key sudah dipakai dengan body request yang berbeda
409	PAYMENT_LINK_NOT_ACTIVE	Payment link sudah tidak menerima pembayaran
409	PAYMENT_NOT_EDITABLE	Transaksi ini sudah tidak bisa menerima percobaan pembayaran baru
429	RATE_LIMITED	Terlalu banyak request — beri jeda lalu coba lagi
500	INTERNAL_ERROR	Error server yang tidak terduga. Aman untuk dicoba ulang
503	SERVICE_UNAVAILABLE	Salah satu dependency (misal database) sedang tidak tersedia
503	AUTH_UNAVAILABLE	Autentikasi sedang tidak tersedia sementara
503	PAYMENT_PROVIDER_UNAVAILABLE	Provider bank/QRIS upstream sedang tidak tersedia sementara

Idempotency

POST /v1/payments mensyaratkan header Idempotency-Key. Mengulang request dengan key yang sama dan body identik akan mengembalikan resource yang sama (bukan duplikat); mengulang dengan body berbeda mengembalikan 409 IDEMPOTENCY_CONFLICT. Ini membuat retry saat network timeout aman dilakukan — lihat panduan Direct Payments.

Mengulang request (retry)

500, 503, dan 429 adalah satu-satunya code yang layak dicoba ulang secara otomatis — beri jeda antar percobaan. Code lainnya berarti request itu sendiri perlu diubah sebelum retry akan membantu.