Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

Katalog Kode Error & Penanganannya

Saat berinteraksi dengan API DagangBot dalam pengembangan integrasi maupun operasional harian, Anda dapat menemui kode balasan error apabila terjadi kegagalan validasi masukan, limitasi kuota paket bisnis, pembatasan rate limiting, atau interupsi teknis pada sisi server (backend). Halaman ini memuat referensi spesifik dari berbagai konstanta kode error (Error Code) internal yang dihasilkan oleh komponen inti sistem kami.

Memahami tipe dan anatomi respons error memungkinkan administrator dan pengembang sistem Anda mengonfigurasi mekanisme coba ulang otomatis (retry logic) yang tangguh, serta memastikan resolusi kendala (troubleshooting) berjalan cepat tanpa kerancuan informasi.

1. Anatomi & Format Respons Error

Seluruh respons kegagalan API platform akan selalu dikonversi menjadi format standar JSON. Objek tingkat tinggi (top-level) error bertugas menyimpan serangkaian properti yang menguraikan konteks kegagalan tersebut:

json
{
  "error": {
    "code": "STRING",
    "message": "STRING",
    "details": "ANY"
  }
}

Rincian struktural masing-masing atribut:

  • code: Merupakan string huruf kapital bernilai konstan secara programatis (contoh: UNAUTHORIZED, QUOTA_EXCEEDED, INVALID_BODY). Tim teknis Anda wajib merujuk pada parameter ini untuk membangun kondisi logika evaluasi (if-else/switch) aplikasi penarik (client application).
  • message: Berisi deskripsi deskriptif tingkat lanjut namun aman untuk ditampilkan kepada pengguna akhir (end-user). Pesan ini telah dirancang untuk menghindari bocornya jejak tumpukan kode (stack trace) yang mengekspos lapisan keamanan.
  • details: Informasi ekstra yang sangat bergantung pada konteks endpoint. Saat Anda berhadapan dengan error bertipe VALIDATION_FAILED, elemen details akan diisi oleh koleksi array yang menyebut spesifikasi field mana yang salah format, nilai yang terlalu panjang, atau properti wajib yang diabaikan.

2. Autentikasi, Identitas & Sesi Kredensial

Segmen ini menaungi kelompok penolakan koneksi akibat izin token tidak valid, permasalahan sesi aplikasi, perlindungan antar-cabang, atau kegagalan proteksi CSRF di ranah portal pengguna.

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
UNAUTHORIZED 401 Akses Mutlak Ditolak Token sesi JWT tidak dilampirkan, sudah mencapai batas umur kedaluwarsa, atau tanda tangan API Key tertolak. Sisipkan kredensial valid pada parameter Header (Authorization: Bearer <token> atau X-API-Key: <key>). Jika via dashboard, lakukan otentikasi login ulang.
FORBIDDEN 403 Akses Terlarang Sementara Identitas kredensial berhasil diverifikasi, namun pengguna dilarang mengeksekusi operasi tersebut oleh lapisan Role-Based Access Control (RBAC). Evaluasi ulang hierarki pengguna dan pastikan posisi akun (Role) berhak mengakses fungsionalitas tersebut pada modul Manajemen Pengguna.
BRANCH_ACCESS_DENIED 403 Batasan Regional Cabang Akun pengguna mengalokasikan pencarian atau penulisan data yang secara eksplisit tidak masuk pada cakupan multi-cabang miliknya. Periksa kecocokan ID cabang yang dikirimkan. Hubungi admin tingkat atas bila staf bersangkutan memerlukan akses cross-branch.
SCOPE_MISMATCH 403 Resolusi Scope Kunci Salah Upaya pemanggilan endpoint yang tidak disokong oleh ketersediaan cakupan (scope) pada API Key All-in-One. Bangkitkan API Key All-in-One baru yang lebih permisif dan tandai scope modul yang menjadi sasaran operasional.
API_KEY_REQUIRED 401 Intersepsi Kunci Nihil Anda lupa memberikan informasi identitas otentikasi mandiri. Jangan memanggil URL protektif secara polosan; selalu lekatkan profil klien pada Header HTTP.
CSRF_FAILED 403 Proteksi Form Lintas Situs Pertukaran token keamanan via Cookie di ranah web mengalami ketidaksesuaian nilai rotasi terbaru. Hindari melakukan manipulasi administratif dari tab peramban ganda. Segarkan (Refresh) ulang antarmuka Anda.

3. Akun Tenant, Restriksi & Penguasaan Kuota

Kode eksepsi yang dikembalikan kala interaksi menabrak perbatasan pembatasan fitur (Plan Gating), hambatan saldo koin, kecepatan trafik ekstrem, atau tumpang tindih pendaftaran aset alamat surel.

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
MISSING_TENANT 400 Konteks Bisnis Tidak Ada Payload atau struktur parameter internal mengabaikan eksistensi pengenal Tenant ID pada rute operasional. Selipkan konfigurasi kustom Tenant ID pada Header (opsional jika dirujuk secara arsitektur).
QUOTA_EXCEEDED 403 Limit Kuota Transaksional Permintaan menginisiasi konsumsi token AI, pengiriman OTP, dan manipulasi layanan lain yang melewati atap paket. Tambah stok koin Anda melalui mekanisme otomatis Top Up & Billing di dasbor komersial.
RATE_LIMIT_EXCEEDED 429 Eksekusi Ekstrem Ditekan Frekuensi pengerjaan hit request dari IP/API Key yang sama membombardir endpoint dalam rentang rasio sangat kecil. Terapkan ritme penundaan terencana (exponential backoff) pada algoritma mesin polling Anda.
EMAIL_TAKEN 409 Duplikasi Entitas Surel Upaya menambah administrator atau tenant baru kandas dikarenakan nama surel sasaran sudah dipatenkan pengguna lain. Wajib mempergunakan serangkaian alamat email unik untuk identitas pembeda.
STORAGE_QUOTA_EXCEEDED 403 Batas Beban Penyimpanan Pengunggahan fail PDF RAG atau ekstensi foto komoditi gagal karena sisa kapasitas direktori menipis. Revitalisasi alokasi media dengan menghapus aset kuno atau beralih menuju tipe paket komersial lebih besar.

4. Perangkat WhatsApp & Infrastruktur Gateway

Integrasi fungsional komunikasi berbalas otomatis bertumpu pada arsitektur node Omnichannel WA. Kesalahan di area ini mencakup limitasi instansiasi alat dan penolakan jembatan transmisi pesan masuk maupun keluar.

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
WA_LIMIT 403 Atap Jumlah Koneksi WA Perintah mengikat sesi WA yang baru disetop paksa oleh batas bawaan paket operasional aktif. Sisihkan peranti virtual yang sedang berstatus statis (tidak terhubung), atau pertimbangkan pengajuan perbesaran paket.
INSTANCE_NOT_FOUND 404 Peranti Tidak Terdaftar Menembakkan logika aksi ke sebuah Instance ID spesifik yang tak lagi menetap di ekosistem platform. Sinkronisasikan ID perangkat Anda di menu konfigurasi Omnichannel WhatsApp.
WA_SEND_FAILED 502 Interupsi Kiriman Pesan Eksekusi jaringan komunikasi tidak tercapai imbas hilangnya otorisasi seluler pelanggan, konektivitas pemancar mati, atau perangkat penerima terblokir sepihak oleh otoritas Meta. Periksa kesinambungan daya dan koneksi internet ponsel utama yang bertindak selaku jembatan sesi.
GATEWAY_UNAVAILABLE 503 Engine Inti Pemancar Mati Platform perantara internal sedang menerima pembaruan versi infrastruktur atau mengalami jeda pemrosesan transien. Mesin memiliki kemampuan pemulihan koneksi parsial secara terotomasi; cobalah jeda sejenak.
WS_TICKET_UNAVAILABLE 503 Rel Sesi Real-Time Terputus Interupsi antrian permintaan tiket sesi WebSocket pada layanan komunikasi dua-arah dashboard. Segarkan memori jendela antarmuka untuk mencetus ulang negosiasi jaringan persisten klien (client persistent network).

5. Mesin Sinkronisasi Konektor Bisnis

Terkait upaya sistem DagangBot bertukar tumpukan informasi secara simultan bersama platform third-party (contoh: platform e-commerce) atau pembacaan instrumen data massal CSV internal.

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
SYNC_FAILED 400 Kolaborasi Antar-Sistem Gugur Kegagalan otentikasi konektor API (misalnya otorisasi Redmine atau Shopee usang) yang membuat platform tujuan me- reject permintaan sinkronisasi. Masuki portal penautan Katalog Konektor lalu sambung ulang sesi kredensial.
IMPORT_FAILED 500 Pemasukan Format CSV Ditolak Berkas yang dilempar tidak melalui penyesuaian bentuk koma (Comma-Separated Values), encoding salah, atau kolom esensial ditinggalkan kosong. Hindari memanipulasi header baris pertama pada file CSV, lalu perbaiki kualitas isian data sebelum mengunggah.
EXPORT_ERROR 500 Kegagalan Agregasi Laporan Proses perangkaian kompilasi tabel mentah melebihi waktu maksimum atau dimensi kapasitas beban RAM berkat jeda tanggal ekstrem. Kurangi jangkauan pengumpulan berkala secara parsial ke batasan bulanan atau per-kuartal.

6. Dinamika Keuangan, Transaksi Pembayaran & Tagihan Koin

Resistensi yang diakibatkan penolakan otorisasi Payment Gateway Xendit/Midtrans, degradasi sirkulasi penagihan faktur, atau defisit amunisi modal transaksi wallet koin pada All-in-One API.

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
PAYMENT_FAILED 500 Penolakan Instrumen Bayar Penyelesaian penyetoran faktur digugurkan secara unilateral oleh jaringan verifikator Payment Gateway. Manfaatkan kanal substitusi (contoh: apabila e-wallet gagal, beralih pada Virtual Account bank).
PAYMENT_UNAVAILABLE 503 Ekosistem Bank Terpuruk Sinkronisasi pengecekan mutasi Xendit/Midtrans dihadapkan pada periode pemeliharaan infrastruktur moneter terjadwal. Simpan niat penyelesaian komersial Anda, coba setorkan instruksi kembali setelah pemeliharaan berlalu.
INSUFFICIENT_BALANCE 400 Kekeringan Saldo Koin Modal Fitur interaktif (notifikasi premium/OTP SMS) diinterupsi sistem keamanan lantaran buku besar portofolio koin nihil (angka 0). Operasikan prosedur Top Up seketika untuk merestorasi nyawa kapabilitas API All-in-One.
TOPUP_FAILED 400 Pemupukan Dana Terganjal Intersepsi jumlah transaksi aktual rekening bank tidak identik sama dengan kode transfer validasi unik tagihan. Teruskan keluhan Anda memuat screenshot penyetoran melalui Kontak & Dukungan.

7. Trasmisi Relai Webhook (Event Notification)

Ketepatan penyaluran sinyal notifikasi eksternal pada infrastruktur milik pelaksana luar sangat berpengaruh pada munculnya rentetan error logikal.

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
WEBHOOK_FAILED 500 Rantai Pelaporan Patah Engine DagangBot gagal melakukan enkapsulasi parameter pada riwayat event bus saat penataan ke database. Tidak menyita atensi intervensi manual pengembang; skenario mitigasi internal platform otomatis menjamin pengiriman tunda.
INVALID_SIGNATURE 400 Tanda Tangan Kriptografi Palsu Fungsi hash penerima mencocokkan signature HMAC dengan kunci rahasia (secret) usang yang telah ditimpa paska rotasi keamanan baru. Pemrogram wajib mengubah susunan secret validation key seragam dengan hasil produksi menu kontrol web.
WEBHOOK_NOT_CONFIGURED 400 Tembok Bisu Tujuan Hilang Rangkaian aksi pesanan atau pelanggan selesai, tapi jalur muara notifikasi belum diputuskan alamat IP maupun domain URL spesifiknya. Berikan masukan URL target ke layar pendaftaran Webhook Eksternal.

8. Modul RAG Vector & Layanan Engine AI

Error khusus yang mewakili perilaku deterministik mesin model bahasa (Large Language Models), distorsi data sumber dokumen vektor Knowledge Base, atau putusnya rel layanan asisten pintar (ASPRI AI).

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
AI_UNAVAILABLE 503 Server Otak Cerdas Tumbang Lapisan abstraksi rotator LLM kami menghadapi downtime provider luar (upstream provider), atau sistem vektor pencarian mati suri sesaat. Platform otomatis merelai penanganan secara asinkron atau menggunakan prosedur fallback bot pesanan statis.
AI_GENERATION_FAILED 502 Halusinasi Pembangkit Konten Konfigurasi teks deskriptif gagal melahirkan luaran berarti imbas penyusunan prompt bernilai ganda atau terlalu rumit. Simplifikasikan parameter aturan direktif pada menu Manajemen Prompt asisten bisnis Anda.
AI_PARSE_FAILED 502 Pemetaan Output Bergeser Teks luaran bot menolak patuh pada aturan ketat format penguraian JSON fungsional (function calling format mismatch). Berikan instruksi lugas ke AI agar mutlak menyisipkan JSON berstruktur bersih pada interaksi spesifik.
FILE_READ_FAILED 400 Restriksi Ekstraksi Teks PDF Berkas dokumen asupan RAG dilapisi perlindungan kata sandi yang menghambat komponen perpustakaan pembaca mengambil konteks kalimat. Rombak properti file; ekspor murni menjadi dokumen tanpa perisai enkripsi, lalu sumbangkan kembali.

9. Kegagalan Fondasi Validasi Standar & Cacat Skema

Masalah lapisan teknis paling bawah, memengaruhi struktur kerangka badan permintaan HTTP (HTTP Request Body) hingga hilangnya data dari referensi database.

Kode HTTP Status Konteks Kegagalan Penyebab Kemunculan Langkah Penyelesaian Terukur
INVALID_BODY 400 Anatomi Payload Hancur Susunan struktur JSON request yang disodorkan dari pihak Anda memiliki anomali pemformatan (misal: kurang tanda kutip penutup) atau ketidaktepatan tipe instrumen integer. Sembuhkan struktur malformasi tersebut sesuai panduan skema murni.
VALIDATION_FAILED 422 Tolak Dokumen Tak Kredibel Secara sintaks format dapat dibaca, namun logika bisnis melarang atribut tersebut (contoh: rentang tanggal terbalik, panjang karakter kerdil, format angka bukan standar E.164 awalan +62). Bongkar parameter details dalam paket JSON error, lalu betulkan spesifik kolom penanda pelanggaran masukan itu.
INVALID_ID 400 Identifier Entitas Ngawur Konstruksi URL sasaran dipenuhi karakter yang menyalahi panjang alfanumerik pengenal unik berbasis UUID sistem standar DagangBot. Pertegas pengutipan ID target dari respons awal, jangan memasukkan tebakan rentetan alfabet secara acak.
NOT_FOUND 404 Kekosongan Rujukan Berbasis Data Meminta pembaruan profil atau pelenyapan entitas komponen (seperti pelanggan dan pesanan) yang tak berjejak sama sekali pada rak database kami. Lakukan pemeriksaan paralel memastikan ID rekaman belum pernah ditelan proses penghapusan berantai (cascade delete) sebelumnya.
INTERNAL_ERROR 500 Kegagalan Bawaan Infrastruktur Kenaikan memori tidak terduga, atau benturan race condition operasional basis data sentral. Anda dibebaskan dari kewajiban komando manual; tim keamanan terdedikasi DagangBot diinformasikan seketika atas semua kelainan berkode 500.

Apabila serangkaian observasi respons ini masih memicu kebuntuan analitik, Anda mutlak disarankan menyelidiki simptom penyerta lainnya melewati artikel dedikasi Pemecahan Masalah Lintas Modul.


10. Batasan Cakupan Galat yang Terdokumentasi

Spesifikasi antarmuka API publik memastikan bentuk respons standar untuk status sukses dan penanganan galat. Daftar kode galat pada halaman ini mencakup seluruh kode penanganan galat resmi yang aktif digunakan di peladen untuk memudahkan penanganan galat (error handling) terprediksi.

content/docs/reference/error-codes.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot