Reason code yang stabil
Error code yang konsisten digunakan dalam logika client, laporan, dan routing tiket otomatis.
Dokumentasi / API Errors
Penanganan API error
Skema terpadu untuk response, error code, gangguan sementara, hasil yang tidak diketahui, diagnosis, dan recovery yang aman untuk integrasi iGaming.
HTTP
hasil request
Kode
penyebab yang jelas
Retry
tindakan aman
Pencarian
diagnosis request
Siklus penanganan error
Dari API response hingga recovery
01
Tentukan jenis hasil
Periksa HTTP status, reason code, kategori error, dan status operasi.
02
Simpan data untuk analisis
Catat request ID dan operation ID, endpoint, waktu, referensi provider, dan parameter yang aman.
03
Pilih tindakan yang aman
Perbaiki data, hentikan operasi, ulangi request setelah jeda, atau periksa status saat ini.
04
Pulihkan dan pantau
Cegah duplikasi, lakukan rekonsiliasi, beri tahu pihak terkait, dan selesaikan akar masalah.
Ringkasan
Error harus menjelaskan penyebab dan tindakan berikutnya
HTTP 400 atau 500 saja tidak cukup. API yang andal mengembalikan reason code yang stabil, menghubungkan response dengan request ID, dan membantu menentukan apakah data perlu diperbaiki, operasi dihentikan, request diulang, atau statusnya diperiksa secara terpisah.
Tindakan yang dapat diprediksi
Kategori error menunjukkan apakah request boleh diulang dan data apa yang perlu diubah.
Korelasi untuk diagnosis
Request ID, operation ID, dan provider ID menghubungkan log client dengan sistem internal dan dukungan.
Struktur error
Struktur response error yang direkomendasikan
Response harus ringkas, stabil, dan dapat diproses otomatis tanpa mengungkap implementasi internal atau data sensitif.
Error code
Identifier penyebab yang stabil dan tidak berubah saat pesan penjelasan diedit.
Deskripsi
Penjelasan singkat dan aman tanpa kode internal, query database, secret, atau detail yang tidak perlu.
Request ID
Identifier unik untuk mencari operasi di log dan menghubungi support.
Data tambahan
Status yang diperbolehkan, limit, kondisi saat ini, atau alasan penolakan yang aman.
Dapat diulang
Penanda eksplisit untuk error sementara yang tetap tidak menggantikan perlindungan terhadap eksekusi ulang operasi.
Jeda sebelum retry
Delay yang direkomendasikan dalam detik atau HTTP header untuk rate limit dan ketidaktersediaan sementara.
Field error
Daftar field bermasalah dengan reason code, path nilai, dan penjelasan yang aman.
Tautan dokumentasi
Tautan permanen atau identifier bagian yang menjelaskan penyebab dan cara memperbaikinya.
Kategori error
Kategori error utama
HTTP status menunjukkan kelas umum hasil, sedangkan kode internal menjelaskan penyebab spesifik dan tindakan yang diperbolehkan.
Input error
Format salah, field wajib tidak ada, nilai tidak didukung, presisi jumlah salah, atau struktur request tidak valid.
Authentication error
Token, API key, signature, timestamp, atau nonce tidak ada, kedaluwarsa, atau tidak valid.
Hak akses tidak mencukupi
Client dikenali tetapi tidak memiliki peran, brand, pasar, atau permission yang diperlukan untuk tindakan tersebut.
Objek tidak ditemukan
Pemain, pembayaran, round, pemeriksaan KYC, provider, atau objek lain tidak ada atau tidak dapat diakses oleh client.
Konflik status
Versi atau status objek berubah, atau identifier operasi sudah digunakan dengan parameter lain.
Pelanggaran business rule
Saldo tidak cukup, limit terlampaui, pemain diblokir, pasar dilarang, atau transisi status tidak diperbolehkan.
Terlalu banyak request
Jumlah request yang diizinkan untuk client, metode, peran, atau operasi kritis telah terlampaui.
Provider tidak tersedia
Layanan eksternal tidak tersedia, merespons lambat, atau sementara tidak menerima operasi.
Internal error
Error platform yang tidak terduga tanpa mengungkap detail internal, tetapi disertai identifier untuk diagnosis.
Retry dan recovery
Retry request dan hasil tidak diketahui
Retry hanya aman setelah jenis error ditentukan dan dipastikan apakah operasi awal mungkin sudah dijalankan.
01
Periksa apakah retry diperbolehkan
Error data, permission, dan business rule biasanya memerlukan perbaikan request, bukan pengiriman ulang.
02
Gunakan operation key yang sama
Retry operasi finansial, game, atau operasi kritis lainnya tidak boleh menghasilkan hasil baru.
03
Perpanjang jeda antarpercobaan
Interval ditingkatkan secara bertahap, mengikuti waktu yang diberikan server, dan membatasi jumlah percobaan total.
04
Hentikan dan teruskan untuk pemeriksaan
Setelah batas percobaan habis, operasi dicatat sebagai belum selesai dan diteruskan untuk pemeriksaan manual atau rekonsiliasi.
Tidak ada response bukan berarti operasi gagal
Jika koneksi terputus setelah request dikirim, hasil dapat tetap tidak diketahui. Sebelum retry, periksa status menggunakan operation ID atau tunggu notifikasi tepercaya.
Diagnosis dan kontrol
Log, identifier, metrik, dan notifikasi
Diagnosis harus dapat merekonstruksi jalur request antara platform, adapter, dan provider eksternal tanpa menyimpan data sensitif yang tidak perlu.
Konteks analisis
Request ID, correlation ID, operation ID, dan external provider ID.
Endpoint, metode HTTP, environment, client, waktu, dan durasi response.
HTTP status, error code, jumlah percobaan, dan status akhir.
Field sensitif yang dimasking, header yang aman, dan hasil verifikasi signature.
Monitoring dan notifikasi
Rasio error berdasarkan metode, provider, client, dan kategori penyebab.
Peningkatan response lambat, HTTP 5xx, signature tidak valid, dan rate limit.
Jumlah retry, operasi dengan hasil tidak diketahui, dan tugas recovery.
Notifikasi dengan threshold, PIC, dan aturan eskalasi.
Testing
Apa yang perlu diuji di test environment
Test environment harus dapat mereproduksi setiap kategori error penting dan memvalidasi perilaku client, retry, dan kontrol yang benar.
Input error
Field yang hilang, tipe salah, nilai tidak didukung, presisi jumlah, dan beberapa error sekaligus.
Akses dan permission
Key salah, token kedaluwarsa, signature tidak valid, peran tidak sesuai, IP dilarang, dan nonce digunakan ulang.
Tidak ada response dan hasil tidak diketahui
Koneksi terputus sebelum pengiriman, setelah operasi diterima, atau saat response akhir dikirim.
Rate limiting
HTTP 429, jeda yang direkomendasikan, request paralel, dan recovery setelah limit berakhir.
Provider error
Ketidaktersediaan, maintenance, response tidak valid, notifikasi tertunda, dan status yang bertentangan.
Retry dan protective stop
Batasi jumlah percobaan, tingkatkan jeda, hentikan request sementara, lakukan recovery terkontrol, dan teruskan masalah secara manual bila diperlukan.
Checklist sebelum peluncuran
Integrasi produksi diluncurkan setelah struktur error, perilaku client, perlindungan duplikasi, dan diagnosis diverifikasi.
Semua error mengembalikan reason code yang stabil dan request ID.
Detail error tidak mengungkap secret atau implementasi internal.
Kategori error sementara dan permanen dijelaskan dalam dokumentasi.
Retry operasi kritis menggunakan duplicate-protection key yang sama.
Hasil yang tidak diketahui ditangani melalui pemeriksaan status atau notifikasi tepercaya.
Log, metrik, notifikasi, recovery queue, dan aturan eskalasi telah disiapkan.
Perlu menyatukan format API error?
Kirim HTTP response saat ini, error code, aturan retry, dan skenario bermasalah. APIACE akan membantu menentukan model error terpadu, recovery yang aman, dan kontrol.