Reason code yang stabil
Error code yang konsisten digunakan dalam logika client, laporan, dan routing tiket automatik.
Dokumentasi / API Errors
Pengendalian API error
Skema bersepadu untuk response, error code, gangguan sementara, hasil yang tidak diketahui, diagnosis, dan recovery yang selamat untuk integrasi iGaming.
HTTP
hasil request
Kod
punca yang jelas
Retry
tindakan selamat
Carian
diagnosis request
Kitaran pengendalian error
Dari API response hingga recovery
01
Tentukan jenis hasil
Semak HTTP status, reason code, kategori error, dan status operasi.
02
Simpan data untuk analisis
Catat request ID dan operation ID, endpoint, masa, referensi provider, dan parameter yang selamat.
03
Pilih tindakan yang selamat
Betulkan data, hentikan operasi, ulangi request selepas jeda, atau semak status semasa ini.
04
Pulihkan dan pantau
Cegah duplicate, lakukan rekonsiliasi, beri tahu pihak berkaitan, dan selesaikan akar masalah.
Ringkasan
Error mesti menjelaskan punca dan tindakan seterusnya
HTTP 400 atau 500 sahaja tidak mencukupi. API yang boleh dipercayai mengembalikan reason code yang stabil, menghubungkan response dengan request ID, dan membantu menentukan adakah data perlu dibetulkan, operasi dihentikan, request diulang, atau statusnya disemak secara berasingan.
Tindakan yang boleh diprediksi
Kategori error menunjukkan adakah request boleh diulang dan data apa yang perlu diubah.
Korelasi untuk diagnosis
Request ID, operation ID, dan provider ID menghubungkan log client dengan sistem dalaman dan sokongan.
Struktur error
Struktur response error yang disyorkan
Response mesti ringkas, stabil, dan boleh diproses automatik tanpa mengungkap implementasi dalaman atau data sensitif.
Error code
Identifier punca yang stabil dan tidak berubah semasa mesej penjelasan diedit.
Penerangan
Penjelasan ringkas dan selamat tanpa kod dalaman, query pangkalan data, secret, atau butiran yang tidak perlu.
Request ID
Identifier unik untuk mencari operasi di log dan menghubungi support.
Data tambahan
Status yang dibenarkan, had, keadaan semasa, atau sebab penolakan yang selamat.
Boleh diulang
Penanda eksplisit untuk error sementara yang tetap tidak menggantikan perlindungan terhadap pelaksanaan semula operasi.
Jeda sebelum retry
Delay yang disyorkan dalam detik atau HTTP header untuk rate had dan ketidaktersediaan sementara.
Field error
Senarai field bermasalah dengan reason code, path nilai, dan penjelasan yang selamat.
Pautan dokumentasi
Pautan permanen atau identifier bahagian yang menjelaskan punca dan cara memperbaikinya.
Kategori error
Kategori error utama
HTTP status menunjukkan kelas umum hasil, manakala kod dalaman menjelaskan punca spesifik dan tindakan yang dibenarkan.
Input error
Format salah, field wajib tiada, nilai tidak disokong, ketepatan jumlah salah, atau struktur request tidak sah.
Authentication error
Token, API key, signature, timestamp, atau nonce tiada, tamat tempoh, atau tidak sah.
Hak akses tidak mencukupi
Client dikenali tetapi tidak memiliki peranan, brand, pasaran, atau permission yang diperlukan untuk tindakan tersebut.
Objek tidak ditemui
Pemain, pembayaran, round, semakan KYC, provider, atau objek lain tiada atau tidak boleh diakses oleh client.
Konflik status
Versi atau status objek berubah, atau identifier operasi telah digunakan dengan parameter lain.
Pelanggaran business rule
Baki tidak mencukupi, had melebihi had, pemain disekat, pasaran dilarang, atau peralihan status tidak dibenarkan.
Terlalu banyak request
Jumlah request yang dibenarkan untuk client, kaedah, peranan, atau operasi kritis telah melebihi had.
Provider tidak tersedia
Perkhidmatan luaran tidak tersedia, merespons perlahan, atau sementara tidak menerima operasi.
Dalaman error
Error platform yang tidak terduga tanpa mengungkap butiran dalaman, tetapi disertai identifier untuk diagnosis.
Retry dan recovery
Retry request dan hasil tidak diketahui
Retry hanya selamat selepas jenis error ditetapkan dan dipastikan adakah operasi awal mungkin telah dijalankan.
01
Semak adakah retry dibenarkan
Error data, permission, dan business rule biasanya memerlukan pembetulan request, bukan penghantaran semula.
02
Gunakan operation key yang sama
Retry operasi kewangan, game, atau operasi kritis lain tidak boleh menghasilkan hasil baharu.
03
Perpanjang jeda antarpercobaan
Selang ditingkatkan secara berperingkat, mengikuti masa yang diberikan server, dan mengehadkan jumlah percubaan total.
04
Hentikan dan teruskan untuk semakan
Selepas had percubaan habis, operasi direkodkan sebagai belum selesai dan diteruskan untuk semakan manual atau rekonsiliasi.
Tiada response bukan berarti operasi gagal
Jika sambungan terputus selepas request dihantar, hasil boleh tetap tidak diketahui. Sebelum retry, semak status menggunakan operation ID atau tunggu notifikasi tepercaya.
Diagnosis dan kawalan
Log, identifier, metrik, dan notifikasi
Diagnosis mesti boleh merekonstruksi laluan request antara platform, adapter, dan provider luaran tanpa menyimpan data sensitif yang tidak perlu.
Konteks analisis
Request ID, correlation ID, operation ID, dan external provider ID.
Endpoint, kaedah HTTP, environment, client, masa, dan durasi response.
HTTP status, error code, jumlah percubaan, dan status akhir.
Field sensitif yang dimasking, header yang selamat, dan hasil pengesahan signature.
Monitoring dan notifikasi
Rasio error berdasarkan kaedah, provider, client, dan kategori punca.
Penambahbaikan response perlahan, HTTP 5xx, signature tidak sah, dan rate had.
Jumlah retry, operasi dengan hasil tidak diketahui, dan tugas recovery.
Notifikasi dengan threshold, PIC, dan peraturan eskalasi.
Testing
Apa yang perlu diuji di testing environment
Testing environment mesti boleh mereproduksi setiap kategori error penting dan memvalidasi tingkah laku client, retry, dan kawalan yang betul.
Input error
Field yang hilang, tipe salah, nilai tidak disokong, ketepatan jumlah, dan beberapa error sekaligus.
Akses dan permission
Key salah, token tamat tempoh, signature tidak sah, peranan tidak sesuai, IP dilarang, dan nonce digunakan semula.
Tiada response dan hasil tidak diketahui
Sambungan terputus sebelum penghantaran, selepas operasi diterima, atau semasa response akhir dihantar.
Rate limiting
HTTP 429, jeda yang disyorkan, request paralel, dan recovery selepas had berakhir.
Provider error
Ketidaktersediaan, maintenance, response tidak sah, notifikasi tertangguh, dan status yang bertentangan.
Retry dan protective stop
Batasi jumlah percubaan, tingkatkan jeda, hentikan request sementara, lakukan recovery terkawal, dan teruskan masalah secara manual bila diperlukan.
Senarai semak sebelum pelancaran
Integrasi produksi dilancarkan selepas struktur error, tingkah laku client, perlindungan duplicate, dan diagnosis disahkan.
Semua error mengembalikan reason code yang stabil dan request ID.
Butiran error tidak mengungkap secret atau implementasi dalaman.
Kategori error sementara dan permanen diterangkan dalam dokumentasi.
Retry operasi kritis menggunakan duplicate-protection key yang sama.
Hasil yang tidak diketahui ditangani melalui semakan status atau notifikasi tepercaya.
Log, metrik, notifikasi, recovery queue, dan peraturan eskalasi telah disediakan.
Perlu menggabungkan format API error?
Hantar HTTP response semasa ini, error code, peraturan retry, dan senario bermasalah. APIACE akan membantu menentukan model error bersepadu, recovery yang selamat, dan kawalan.