Kode error

Semua kegagalan Billing API dijawab dengan kode error simbolik pada error.code — jangan bergantung pada angka status HTTP saja untuk menentukan penanganan.

Bentuk amplop error

Setiap respons gagal berbentuk objek error dengan code dan message. Sebagian kode menambahkan field lain yang relevan — contohnya EXTERNAL_ID_CONFLICT menyertakan invoiceId dan number milik invoice yang sudah ada:

{
  "error": {
    "code": "EXTERNAL_ID_CONFLICT",
    "message": "externalId ORD-2026-0912 sudah dipakai",
    "invoiceId": "clx9a",
    "number": "INV-2026-0012"
  }
}

Daftar kode error

Kode	HTTP	Arti	Saran penanganan
VALIDATION_ERROR	400	Payload tidak lolos validasi. Field yang bermasalah dirinci pada `issues`.	Perbaiki field yang disebut pada `issues`, lalu kirim ulang.
INVOICE_ALREADY_PAID	400	Link pembayaran diminta untuk invoice yang sudah lunas.	Tidak perlu diulang — periksa status invoice lebih dulu.
UNAUTHORIZED	401	Header Authorization hilang, API key salah, atau key sudah dicabut.	Periksa header dan status key di Dashboard → Integrasi API.
CUSTOMER_NOT_FOUND	404	Pelanggan tidak ada di organisasi pemilik key.	Buat pelanggan lebih dulu lewat POST /v1/customers.
PRODUCT_NOT_FOUND	404	Produk tidak ada di organisasi pemilik key.	Buat produk lebih dulu, atau kirim item tanpa productId.
INVOICE_NOT_FOUND	404	Invoice tidak ada di organisasi pemilik key.	Periksa kembali id atau externalId yang dipakai.
RESOURCE_NOT_FOUND	404	Resource yang diminta tidak ditemukan.	Periksa kembali path dan id yang dikirim.
EXTERNAL_ID_CONFLICT	409	externalId sudah dipakai invoice lain di organisasi Anda.	Badan respons memuat invoiceId dan number invoice yang sudah ada. Kalau ini pengulangan request yang sempat timeout, ambil invoice itu lewat GET /v1/invoices/external/{externalId} — jangan membuat ulang dengan ID berbeda.
INTERNAL_ERROR	500	Kesalahan tak terduga di sisi kami.	Periksa status invoice sebelum mengulang, lalu coba lagi beberapa saat kemudian.