Kode error API

Kalau permintaan ke API gagal, Konek QR menjawab dengan status HTTP 4xx atau 5xx dan badan application/problem+json (RFC 9457). Halaman ini mendaftar setiap code, artinya, dan apa yang perlu kamu lakukan.

Bentuk error

{
  "type": "https://konekqr.web.id/errors/invalid_api_key",
  "title": "Invalid API key",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "API key tidak ada, salah, atau sudah dicabut. Kirim header Authorization: Bearer kq_live_… atau kq_test_…."
}

• Buat programmu memeriksa code. Nilainya tidak berubah antarversi.
• title dan detail untuk dibaca orang. detail berbahasa Indonesia; kirim header Accept-Language: en untuk bahasa Inggris.
• type membuka bagian kode itu di halaman ini.
• 422 validation_failed juga membawa daftar errors: satu baris per isian, masing-masing dengan field, code, dan message.

Kapan aman mengulang

• 429 rate_limited: tunggu sesuai header Retry-After (dalam detik), lalu ulangi.
• 500 internal_error atau timeout: ulangi dengan Idempotency-Key yang sama. Kalau tagihannya ternyata sudah dibuat, kamu mendapat tagihan yang sama, bukan tagihan kedua.
• 409 idempotency_in_progress: permintaan pertama masih berjalan. Ulangi beberapa detik lagi dengan key yang sama.
• Error 4xx lainnya akan gagal lagi kalau diulang apa adanya. Perbaiki permintaannya, atau keadaan akunnya, dulu.

400 Permintaan tidak bisa dibaca

invalid_json

Badan permintaan bukan JSON yang valid, atau memuat isian yang tidak dikenal. Isian asing sengaja ditolak, supaya salah ketik seperti referenceID tidak diam-diam diabaikan.

Periksa JSON-nya dan nama setiap isian di Referensi API.

idempotency_key_invalid

Header Idempotency-Key tidak ada, atau lebih dari 100 karakter. Header ini wajib di POST /v1/payments.

Kirim satu key per pesanan, misalnya order-1001, dan pakai key yang sama saat mengulang permintaan itu.

401 API key ditolak

invalid_api_key

API key tidak ada, salah, sudah dicabut, atau akunnya sedang dinonaktifkan. Jawaban ini juga membawa header WWW-Authenticate: Bearer.

Kirim Authorization: Bearer kq_live_… atau kq_test_…. Kalau key-nya benar tapi tetap ditolak, cek di dashboard apakah key itu masih aktif, atau hubungi [email protected].

403 Tidak diizinkan

insufficient_scope

Key ini tidak punya izin (scope) untuk permintaan ini. Scope yang ada: payments:read, payments:write, dan events:read.

Buat key dengan scope yang dibutuhkan di dashboard, lalu cabut key yang lama.

browser_not_allowed

Permintaan datang dari browser (membawa header Origin). API key hanya untuk server, jadi permintaan seperti ini selalu ditolak supaya key tidak bocor lewat halaman web.

Panggil API dari servermu, lalu kirim hasilnya, misalnya payUrl atau qrString, ke halaman pembeli.

cross_origin_rejected

Permintaan yang mengubah data datang dari browser di situs lain. Ini perlindungan terhadap CSRF.

Sama seperti browser_not_allowed: panggil API dari server, bukan dari browser.

test_mode_only

POST /v1/payments/{id}/simulate dipanggil dengan key live, atau untuk tagihan live. Simulasi hanya ada di mode uji; tagihan live hanya lunas lewat pembayaran sungguhan.

Pakai key kq_test_… dan tagihan uji untuk mencoba alur lunas.

404 Tidak ditemukan

not_found

Tidak ada tagihan dengan id itu di akun dan mode key-mu, atau qrisId yang kamu kirim bukan QRIS di akunmu. Key uji tidak melihat tagihan live, dan key live tidak melihat tagihan uji.

Cek id-nya, dan pastikan kamu memakai key dari mode yang sama dengan saat tagihan dibuat.

409 Bertabrakan dengan keadaan akun

qris_not_ready

Belum ada QRIS yang bisa dipakai. Tagihan live butuh QRIS yang sudah terverifikasi dan sudah lewat masa tunggu 24 jam. Tagihan uji cukup dengan QRIS apa saja di akunmu, terverifikasi atau belum.

Tambahkan atau verifikasi QRIS di dashboard. QRIS tambahan di akun yang sudah pernah punya QRIS terverifikasi baru bisa dipakai 24 jam setelah terverifikasi.

balance_negative

Saldo biaya akunmu minus, jadi tagihan live baru ditahan. Mode uji tetap jalan, dan tagihan yang sudah dibuat tidak terpengaruh.

Isi saldo di dashboard. Tagihan live bisa dibuat lagi begitu saldonya tidak minus. Aturannya ada di Kebijakan Saldo.

nmid_mismatch

NMID QRIS yang akan dipakai tidak sama dengan expectedNmid yang kamu kirim. Tagihan tidak dibuat, jadi pembeli tidak pernah melihat QR ke QRIS yang tidak kamu harapkan.

Cek QRIS di dashboard. Kalau QRIS-nya memang baru diganti, perbarui expectedNmid di sistemmu.

detection_offline

Kamu mengirim requireDetection: true, dan tidak ada HP Listener yang aktif dalam 7 menit terakhir. Tagihan tidak dibuat, karena pembayarannya tidak akan terkonfirmasi otomatis.

Nyalakan HP kasir dan pastikan Listener berjalan. Atau buat tagihan tanpa requireDetection dan konfirmasi pembayarannya secara manual.

too_many_pending

Sudah ada 200 tagihan yang menunggu pembayaran di mode ini.

Batalkan tagihan yang tidak akan dibayar, atau pakai masa berlaku yang lebih pendek lewat expiresInMinutes.

unique_codes_exhausted

Semua total unik untuk nominal ini sedang dipakai tagihan lain di akunmu untuk provider yang sama. Sebuah total dikunci sejak tagihannya dibuat sampai 24 jam setelah kedaluwarsa.

Coba lagi nanti, atau ubah nominalnya sedikit.

reference_taken

referenceId ini sudah dipakai tagihan lain di mode yang sama.

Pakai referenceId yang unik per pesanan. Untuk mengulang permintaan tanpa membuat tagihan kedua, pakai Idempotency-Key, bukan referenceId.

payment_not_pending

Tagihan ini sudah lunas atau dibatalkan, jadi tidak bisa dibatalkan atau disimulasikan lagi.

Baca status terbarunya dengan GET /v1/payments/{id}.

qris_seal_invalid

Isi QRIS yang tersimpan tidak cocok lagi dengan segelnya, jadi Konek QR berhenti memakainya. Segel ini ada supaya QRIS-mu tidak bisa ditukar diam-diam.

Jangan buat tagihan dari QRIS ini. Hubungi [email protected].

idempotency_conflict

Idempotency-Key ini sudah dipakai untuk permintaan dengan isi berbeda dalam 24 jam terakhir.

Pakai key baru untuk pesanan baru. Saat mengulang, kirim isi yang persis sama.

idempotency_in_progress

Permintaan dengan Idempotency-Key ini masih diproses.

Ulangi beberapa detik lagi dengan key dan isi yang sama.

413 Badan terlalu besar

payload_too_large

Badan permintaan lebih dari 64 KiB.

Perkecil isinya. metadata sendiri maksimal 4 KB.

422 Isian tidak valid

validation_failed

Satu isian atau lebih tidak valid. Daftar errors menyebut setiap isian dengan code-nya sendiri:

Perbaiki nilainya sesuai tabel, atau tampilkan message ke penggunamu.

429 Terlalu banyak permintaan

rate_limited

Batasnya 120 permintaan per menit per key, dan 120 tagihan baru per menit per akun untuk setiap mode.

Tunggu sesuai header Retry-After, lalu ulangi. Untuk menunggu pembayaran, pakai webhook atau GET /v1/events?wait=30, bukan memanggil GET /v1/payments/{id} berulang kali.

500 Kesalahan di sisi kami

internal_error

Ada yang gagal di server Konek QR. Permintaanmu tidak salah.

Ulangi dengan jeda yang makin panjang. Saat membuat tagihan, pakai Idempotency-Key yang sama supaya tidak ada tagihan ganda. Kalau terus terjadi, cek status layanan atau kabari [email protected].