Stable reason code
Ginagamit ang permanent error code sa client logic, reports at automated routing ng support requests.
Documentation / API Errors
API error handling
Iisang approach para sa responses, error codes, temporary failures, unknown results, diagnostics at safe recovery sa iGaming integrations.
HTTP
request result
Codes
malinaw na dahilan
Retry
safe na aksyon
Search
request diagnostics
Error handling cycle
Mula API response hanggang recovery
01
Tukuyin ang uri ng result
Suriin ang HTTP status, reason code, error category at operation state.
02
I-save ang data para sa analysis
I-record ang request at operation IDs, endpoint, oras, provider reference at safe parameters.
03
Pumili ng safe na aksyon
Ayusin ang data, ihinto ang operation, mag-retry pagkatapos ng pause o suriin ang kasalukuyang state.
04
I-recover at i-monitor
Iwasan ang duplicates, magsagawa ng reconciliation, i-notify ang responsible teams at isara ang root cause ng failure.
Overview
Dapat ipaliwanag ng error ang dahilan at susunod na aksyon
Hindi sapat ang HTTP 400 o 500 response lang. Ang reliable API ay nagbabalik ng stable reason code, nag-uugnay ng response sa request ID at malinaw na nagpapakita kung dapat ayusin ang data, ihinto ang operation, mag-retry o hiwalay na suriin ang state.
Predictable na aksyon
Ipinapakita ng error category kung puwedeng mag-retry at anong data ang kailangang baguhin.
Link para sa diagnostics
Ang request, operation at provider IDs ang nag-uugnay sa client logs, internal systems at support.
Error structure
Inirerekomendang error response structure
Dapat compact, stable at machine-processable ang response nang hindi inilalantad ang internal implementation o sensitive data.
Error code
Stable identifier ng dahilan na hindi nagbabago kapag ine-edit ang explanatory message.
Description
Maikling safe na paliwanag na walang internal code, database queries, secrets o hindi kailangang detalye.
Request ID
Unique identifier para mahanap ang operation sa logs at sa support request.
Karagdagang data
Allowed status, limit, current state o safe na dahilan ng rejection.
Maaaring i-retry
Malinaw na indikasyon ng temporary error na hindi inaalis ang duplicate protection ng operation.
Pause bago mag-retry
Inirerekomendang delay sa seconds o HTTP header para sa rate limiting at temporary unavailability.
Field errors
Listahan ng problem fields kasama ang reason code, path sa value at safe na explanation.
Documentation link
Permanent link o section identifier na may description ng dahilan at paraan ng pag-aayos.
Error categories
Pangunahing error categories
Ipinapakita ng HTTP status ang general result class, habang nililinaw ng internal code ang eksaktong dahilan at allowed action.
Input data error
Maling format, kulang na required field, unsupported value, amount precision issue o invalid request structure.
Authentication error
Missing, expired o invalid token, API key, signature, request time o one-time identifier.
Kulang ang permissions
Nakilala ang client ngunit wala itong tamang role, brand, market o permission para sa action.
Hindi nakita ang object
Walang player, payment, round, KYC check, provider o ibang object, o hindi ito accessible sa client.
State conflict
Nagbago ang version o state ng object, o nagamit na ang operation ID na may ibang parameters.
Business rule violation
Insufficient balance, exceeded limit, blocked player, prohibited market o invalid status transition.
Masyadong maraming requests
Lumampas sa allowed request count para sa client, method, role o critical operation.
Hindi available ang provider
Hindi available ang external service, mabagal sumagot o pansamantalang hindi tumatanggap ng operations.
Internal error
Unexpected platform error nang hindi inilalantad ang internal details, ngunit may identifier para sa diagnostics.
Retry at recovery
Request retry at unknown result
Ligtas lamang ang retry pagkatapos matukoy ang error type at masuri kung maaaring naisagawa na ang original operation.
01
Suriin kung pinapayagan ang retry
Karaniwang kailangan munang ayusin ang request para sa data, permission at business-rule errors sa halip na ipadala ulit.
02
Gamitin ang parehong operation key
Ang retry ng financial, gaming o ibang critical operation ay hindi dapat gumawa ng bagong result.
03
Dagdagan ang pause sa pagitan ng attempts
Unti-unting pinahahaba ang intervals, sinusunod ang server-specified timing at nililimitahan ang kabuuang attempts.
04
Ihinto at ipadala para sa review
Kapag naubos ang attempts, mamarkahan ang operation bilang incomplete at ipapasa sa manual review o reconciliation.
Ang kawalan ng response ay hindi nangangahulugang rejected ang operation
Kapag naputol ang connection pagkatapos maipadala ang request, maaaring manatiling unknown ang result. Bago mag-retry, suriin ang state gamit ang operation ID o hintayin ang trusted notification.
Diagnostics at control
Logs, identifiers, metrics at notifications
Dapat ma-reconstruct ng diagnostics ang request path sa pagitan ng platform, adapter at external provider nang hindi nag-iimbak ng hindi kailangang sensitive data.
Context para sa analysis
Request, correlation, operation at external provider IDs.
Endpoint, HTTP request method, environment, client, oras at response duration.
HTTP status, error code, bilang ng attempts at final state.
Masked sensitive fields, safe headers at signature verification result.
Monitoring at notifications
Error rate ayon sa method, provider, client at reason category.
Pagtaas ng slow responses, HTTP 5xx, invalid signatures at rate-limit events.
Bilang ng retries, operations na may unknown result at recovery tasks.
Notifications na may thresholds, owners at escalation rules.
Testing
Ano ang dapat i-test sa test environment
Dapat ma-reproduce ng test environment ang bawat importanteng error category at makumpirma ang tamang behavior ng client, retries at controls.
Input data errors
Missing fields, wrong types, unsupported values, amount precision issues at maraming errors nang sabay.
Access at permissions
Invalid key, expired token, incorrect signature, wrong role, prohibited IP at reused one-time identifier.
Walang response at unknown result
Connection failure bago maipadala, pagkatapos tanggapin ang operation at habang hinihintay ang final response.
Rate limiting
HTTP 429, recommended pause, parallel requests at recovery pagkatapos matapos ang limit.
Provider errors
Unavailability, maintenance, invalid response, delayed notification at conflicting status.
Retry at protective stop
Paglilimita ng attempts, mas mahabang pauses, pansamantalang paghinto ng requests, controlled recovery at manual escalation.
Pre-launch checklist
Inilulunsad ang production integration pagkatapos masuri ang error structure, client behavior, duplicate protection at diagnostics.
Ang lahat ng errors ay nagbabalik ng stable reason code at request ID.
Hindi inilalantad ng error details ang secrets o internal implementation.
Naka-dokumento ang temporary at permanent error categories.
Ginagamit ng retry ng critical operation ang parehong duplicate-protection key.
Ang unknown result ay hinahandle sa pamamagitan ng state check o trusted notification.
Naka-configure ang logs, metrics, notifications, recovery queue at escalation rules.
Kailangang gawing iisa ang format ng API errors?
Ipadala ang kasalukuyang HTTP responses, error codes, retry rules at problematic scenarios. Tutulungan ng APIACE na tukuyin ang unified error model, safe recovery at control.