Stable reason code
Stable error code hutumika kwenye client logic, reporting na automatic enquiry routing.
Documentation / API Errors
API error handling
Mfumo mmoja wa responses, error codes, temporary failures, unknown outcomes, diagnostics na safe recovery kwa iGaming integrations.
HTTP
matokeo ya request
Codes
sababu wazi
Retry
hatua salama
Trace
request diagnostics
Error-handling cycle
Kutoka API response hadi recovery
01
Tambua aina ya outcome
Kagua HTTP status, reason code, error category na operation state.
02
Hifadhi data kwa investigation
Rekodi request na operation identifiers, endpoint, muda, provider reference na parameters salama.
03
Chagua hatua salama
Sahihisha data, simamisha operation, retry baada ya delay au kagua current state.
04
Recover na verify
Zuia duplicates, fanya reconciliation, wajulishe responsible teams na funga root cause.
Overview
Error inapaswa kueleza sababu na hatua inayofuata
HTTP 400 au 500 response pekee haitoshi. API ya kuaminika hutoa stable reason code, huunganisha response na request identifier na kuonyesha wazi kama data inahitaji kusahihishwa, operation kusimamishwa, request kufanywa retry au state yake kukaguliwa tofauti.
Hatua inayotabirika
Error category huonyesha kama request inaweza kufanywa retry na ni data gani inahitaji kubadilishwa.
Diagnostic correlation
Request, operation na provider identifiers huunganisha client logs na internal systems pamoja na support.
Error structure
Muundo unaopendekezwa wa error response
Response inapaswa kuwa compact, stable na kufaa automated processing bila kufichua internal implementation au sensitive data.
Error code
Identifier thabiti ya sababu ambayo haibadiliki wakati explanatory message inahaririwa.
Maelezo
Maelezo mafupi na salama bila internal code, database queries, secrets au details zisizohitajika.
Request ID
Identifier ya kipekee ya kupata operation kwenye logs na kuwasiliana na support.
Data ya ziada
Status inayoruhusiwa, limit, current state au sababu salama ya rejection.
Retryable
Ishara wazi ya temporary error ambayo haiondoi duplicate protection ya operation.
Delay kabla ya retry
Delay inayopendekezwa kwa seconds au HTTP header kwa rate limiting na temporary unavailability.
Field errors
Orodha ya fields zenye tatizo pamoja na reason code, value path na maelezo salama.
Documentation reference
Permanent link au section identifier inayoeleza sababu na jinsi ya kuitatua.
Error categories
Main error categories
HTTP status huonyesha outcome class ya jumla, huku internal code ikibainisha sababu maalum na action inayoruhusiwa.
Input validation error
Invalid format, required field iliyokosekana, unsupported value, amount precision isiyo sahihi au invalid request structure.
Authentication error
Token, API key, signature, request timestamp au nonce iliyokosekana, expired au invalid.
Permissions hazitoshi
Client imetambuliwa lakini haina role, brand, market au permission inayohitajika kwa action hiyo.
Object haijapatikana
Player, payment, round, KYC check, provider au object nyingine haipo au haipatikani kwa client.
State conflict
Version au state ya object imebadilika, au operation identifier tayari imetumika na parameters tofauti.
Ukiukaji wa business rule
Balance haitoshi, limit imezidi, player amezuiwa, market imekatazwa au status transition si halali.
Requests nyingi sana
Idadi inayoruhusiwa ya requests kwa client, method, role au critical operation imezidi.
Provider hapatikani
External service haipatikani, inajibu kwa kuchelewa au kwa muda haikubali operations.
Internal error
Platform error isiyotarajiwa bila kufichua internal details, lakini ikiwa na identifier ya diagnostics.
Retries na recovery
Request retry na unknown outcome
Retry ni salama tu baada ya kutambua error type na kukagua kama original operation huenda tayari ilikamilika.
01
Kagua kama retry inaruhusiwa
Data, permission na business-rule errors kwa kawaida huhitaji request isahihishwe badala ya kutumwa tena.
02
Tumia operation key ileile
Retry ya financial, gaming au critical operation nyingine haipaswi kuunda result mpya.
03
Ongeza delay kati ya attempts
Intervals huongezeka hatua kwa hatua, huzingatia delay iliyotolewa na server na kuweka kikomo cha jumla cha attempts.
04
Simamisha na peleka kwa review
Baada ya attempts zote kuisha, operation hurekodiwa kama incomplete na kupelekwa manual review au reconciliation.
Kutopata response hakumaanishi operation imefaili
Connection ikikatika baada ya request kutumwa, outcome inaweza kubaki unknown. Kabla ya retry, kagua state kwa operation identifier au subiri trusted notification.
Diagnostics na control
Logs, identifiers, metrics na alerts
Diagnostics zinapaswa kurejesha request path kati ya platform, adapter na external provider bila kuhifadhi sensitive data zisizohitajika.
Investigation context
Request, correlation, operation na external provider identifiers.
Endpoint, HTTP method, environment, client, muda na response duration.
HTTP status, error code, idadi ya attempts na final state.
Masked sensitive fields, safe headers na signature validation result.
Monitoring na alerts
Error rate kwa method, provider, client na reason category.
Kuongezeka kwa slow responses, HTTP 5xx errors, invalid signatures na rate-limit events.
Idadi ya retries, operations zenye unknown outcomes na recovery tasks.
Alerts zenye thresholds, owners na escalation rules.
Testing
Nini cha kutest kwenye test environment
Test environment inapaswa kurudia kila important error category na kuthibitisha tabia sahihi ya client, retries na controls.
Input validation errors
Fields zilizokosekana, invalid types, unsupported values, amount precision na errors nyingi kwa wakati mmoja.
Access na permissions
Invalid key, expired token, incorrect signature, role isiyoruhusiwa, blocked IP na reused nonce.
Hakuna response na outcome haijulikani
Connection failure kabla ya kutuma, baada ya operation kukubaliwa na wakati wa kupokea final response.
Rate limiting
HTTP 429, delay inayopendekezwa, concurrent requests na recovery baada ya limit kuisha.
Provider errors
Unavailability, maintenance, invalid response, delayed notification na conflicting status.
Retry na protective stop
Kuweka kikomo cha attempts, kuongeza delays, kusimamisha requests kwa muda, controlled recovery na manual escalation.
Pre-launch checklist
Production integration huzinduliwa baada ya kuthibitisha error structure, client behavior, duplicate protection na diagnostics.
Errors zote hurudisha stable reason code na request identifier.
Error details hazifichui secrets au internal implementation.
Temporary na permanent error categories zimeandikwa kwenye documentation.
Critical operation inayofanywa retry hutumia idempotency key ileile.
Unknown outcome hushughulikiwa kwa kukagua state au kupokea trusted notification.
Logs, metrics, alerts, recovery queue na escalation rules zimewekwa.
Unahitaji kuweka API errors katika standard moja?
Tutumie HTTP responses za sasa, error codes, retry rules na problematic scenarios. APIACE itasaidia kufafanua unified error model, safe recovery na control approach.