Bisadagang BisnisBisadagang BisnisDocs
HargaMasukDaftar gratis
Mulai
  • Pengenalan
  • Quick start
Dasar
  • Autentikasi & signature
  • Format respons & kode error
Referensi API
  • GETCek saldo
  • GETDaftar harga & produk
  • Transaksi
  • Komplain
  • Webhook
Panduan
  • Sandbox
  • Panduan vibe coder
Butuh bantuan?

Tim teknis kami siap membantu integrasi lewat WhatsApp.

Chat tim teknis
Syarat dan ketentuanKebijakan privasi
Mulai
  • Pengenalan
  • Quick start
Dasar
  • Autentikasi & signature
  • Format respons & kode error
Referensi API
  • GETCek saldo
  • GETDaftar harga & produk
  • Transaksi
  • Komplain
  • Webhook
Panduan
  • Sandbox
  • Panduan vibe coder
Dasar

Format respons & kode error

Semua endpoint memakai format respons yang sama. Cek field success, lalu baca data atau error.

Respons sukses#

Status HTTP 2xx dengan success: true. Isi data berbeda per endpoint dan dijelaskan di halaman endpoint masing-masing.

200 OK
{
  "success": true,
  "data": { … },
  "request_id": "a1b2c3d4e5"
}

Respons error#

Status HTTP 4xx atau 5xx dengan success: false dan objek error.

403 · IP_NOT_WHITELISTED
{
  "success": false,
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "IP 203.0.113.10 tidak terdaftar untuk API key ini.",
    "details": { "ip": "203.0.113.10" }
  },
  "request_id": "a1b2c3d4e5"
}
Field
Isi
error.code
Kode tetap untuk dibaca program. Buat logika berdasarkan field ini.
error.message
Penjelasan dalam bahasa Indonesia untuk manusia. Teksnya bisa berubah, jangan dipakai untuk logika.
error.details
Informasi tambahan sesuai kode, atau null.

request_id#

Setiap respons, sukses maupun error, membawa request_id: 10 karakter hex yang unik per request. Simpan di log Anda dan sertakan saat menghubungi tim teknis supaya request-nya bisa langsung kami telusuri.

Kode error#

Kode yang bisa dikembalikan oleh endpoint yang tersedia saat ini:

Kode
HTTP
Arti
VALIDATION_ERROR400
400
Parameter atau body tidak valid. Daftar masalahnya ada di details.
INVALID_API_KEY401
401
API key kosong, tidak dikenal, atau sudah dicabut.
TIMESTAMP_OUT_OF_RANGE401
401
Timestamp bukan detik Unix atau selisihnya lebih dari 300 detik.
INVALID_SIGNATURE401
401
Signature tidak cocok.
NONCE_REUSED401
401
Nonce sudah pernah dipakai.
HTTPS_REQUIRED403
403
Request dikirim lewat HTTP.
PARTNER_NOT_ACTIVE403
403
Akun Mitra Bisnis belum aktif.
PARTNER_SUSPENDED403
403
Akun Mitra Bisnis dibekukan.
IP_NOT_WHITELISTED403
403
IP tidak ada di whitelist. IP yang terlihat ada di details.ip.
UNSUPPORTED_CONTENT_TYPE415
415
Body bukan JSON.
INSUFFICIENT_BALANCE422
422
Saldo kurang dari harga produk. Saldo tidak terpotong; harga yang dibutuhkan ada di details.price. Lihat Saldo tidak cukup.
RATE_LIMITED429
429
Batas request per menit tercapai. Lihat Batas request.
INTERNAL_ERROR500
500
Kesalahan di server Bisadagang. Coba lagi beberapa saat kemudian.
SERVICE_MAINTENANCE503
503
Layanan sedang gangguan atau pemeliharaan. Coba lagi beberapa saat kemudian.
Kode yang khas untuk transaksi (mis. produk gangguan, harga berubah, atau inquiry kedaluwarsa) ada di Transaksi: kode error. Jika menerima kode yang belum Anda kenal, tangani berdasarkan status HTTP-nya.

Error validasi#

Untuk VALIDATION_ERROR dari parameter yang salah, details berisi daftar pesan, satu per masalah. Pesan ini dalam bahasa Inggris.

400 · VALIDATION_ERROR
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Permintaan tidak valid.",
    "details": ["status must be one of the following values: normal, gangguan"]
  },
  "request_id": "a1b2c3d4e5"
}

Batas request#

Batas dihitung per Mitra Bisnis, per environment, dalam jendela 1 menit. Cek saldo dan daftar produk masuk kelompok baca dengan batas default 120 request per menit. Batas bisa berbeda per Mitra Bisnis; nilai yang berlaku selalu ada di header respons.

Header respons
Isi
X-RateLimit-Limit
Batas request per menit untuk kelompok endpoint ini.
X-RateLimit-Remaining
Sisa request di menit berjalan.
Retry-After
Hanya pada 429: detik sampai jendela berikutnya dibuka.
429 · RATE_LIMITED
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Batas 120 permintaan per menit tercapai. Coba lagi dalam 23 detik.",
    "details": { "limit": 120, "group": "read", "retry_after_seconds": 23 }
  },
  "request_id": "a1b2c3d4e5"
}
  • Saat menerima 429, tunggu sesuai Retry-After lalu ulangi dengan timestamp, nonce, dan signature baru.
  • Daftar produk tidak perlu diambil di setiap transaksi. Simpan di cache dan perbarui secara berkala.
Sebelumnya
Autentikasi & signature
Berikutnya
Cek saldo
Butuh bantuan?
Tanya soal integrasi teknis lewat WhatsApp.
Chat di WhatsApp
Di halaman ini
  • Respons sukses
  • Respons error
  • request_id
  • Kode error
  • Error validasi
  • Batas request