Stable reason code
A stable error code is used in client logic, reporting and automatic enquiry routing.
Documentation / API Errors
API error handling
A unified model for responses, error codes, temporary failures, unknown outcomes, diagnostics and safe recovery for iGaming integrations.
HTTP
request outcome
Codes
clear reason
Retry
safe action
Trace
request diagnostics
Error-handling cycle
From API response to recovery
01
Determine the outcome type
Check the HTTP status, reason code, error category and operation state.
02
Save data for investigation
Record the request and operation identifiers, endpoint, time, provider reference and safe parameters.
03
Choose a safe action
Correct the data, stop the operation, retry after a delay or check the current state.
04
Recover and verify
Prevent duplicates, reconcile results, notify responsible teams and close the root cause.
Overview
An error should explain the cause and the next action
An HTTP 400 or 500 response alone is not enough. A reliable API returns a stable reason code, links the response to a request identifier and makes it clear whether data must be corrected, the operation stopped, the request retried or its state checked separately.
Predictable action
The error category indicates whether the request can be retried and what data needs to change.
Diagnostic correlation
Request, operation and provider identifiers link client logs with internal systems and support.
Error structure
Recommended error response structure
The response should be compact, stable and suitable for automated processing without exposing internal implementation or sensitive data.
Error code
A stable identifier for the reason that does not change when the explanatory message is edited.
Description
A brief, safe explanation without internal code, database queries, secrets or unnecessary detail.
Request ID
A unique identifier for locating the operation in logs and contacting support.
Additional data
An allowed status, limit, current state or safe reason for rejection.
Retryable
An explicit indication of a temporary error that does not remove duplicate protection for the operation.
Delay before retry
A recommended delay in seconds or an HTTP header for rate limiting and temporary unavailability.
Field errors
A list of problematic fields with a reason code, value path and safe explanation.
Documentation reference
A permanent link or section identifier describing the cause and how to fix it.
Error categories
Main error categories
The HTTP status indicates the general outcome class, while the internal code identifies the specific cause and permitted action.
Input validation error
Invalid format, a missing required field, an unsupported value, incorrect amount precision or an invalid request structure.
Authentication error
A missing, expired or invalid token, API key, signature, request timestamp or nonce.
Insufficient permissions
The client is recognised but does not have the required role, brand, market or permission for the action.
Object not found
A player, payment, round, KYC check, provider or other object does not exist or is not available to the client.
State conflict
The object's version or state has changed, or the operation identifier has already been used with different parameters.
Business rule violation
Insufficient balance, exceeded limit, blocked player, prohibited market or invalid status transition.
Too many requests
The permitted request count for the client, method, role or critical operation has been exceeded.
Provider unavailable
The external service is unavailable, responds slowly or is temporarily not accepting operations.
Internal error
An unexpected platform error without exposing internal details, but with an identifier for diagnostics.
Retries and recovery
Request retry and unknown outcome
A retry is safe only after identifying the error type and checking whether the original operation may already have completed.
01
Check whether retry is allowed
Data, permission and business-rule errors usually require the request to be corrected rather than resent.
02
Keep the same operation key
Retrying a financial, gaming or other critical operation must not create a new result.
03
Increase the delay between attempts
Intervals increase progressively, respect the server-provided delay and limit the total number of attempts.
04
Stop and escalate for review
After all attempts are exhausted, the operation is recorded as incomplete and sent for manual review or reconciliation.
No response does not mean the operation failed
If the connection drops after a request is sent, the outcome may remain unknown. Before retrying, check the state using the operation identifier or wait for a trusted notification.
Diagnostics and control
Logs, identifiers, metrics and alerts
Diagnostics should reconstruct the request path between the platform, adapter and external provider without storing unnecessary sensitive data.
Investigation context
Request, correlation, operation and external provider identifiers.
Endpoint, HTTP method, environment, client, time and response duration.
HTTP status, error code, number of attempts and final state.
Masked sensitive fields, safe headers and signature validation result.
Monitoring and alerts
Error rate by method, provider, client and reason category.
Increases in slow responses, HTTP 5xx errors, invalid signatures and rate-limit events.
Number of retries, operations with unknown outcomes and recovery tasks.
Alerts with thresholds, owners and escalation rules.
Testing
What to test in the test environment
The test environment should reproduce every important error category and confirm correct client, retry and control behaviour.
Input validation errors
Missing fields, invalid types, unsupported values, amount precision and multiple simultaneous errors.
Access and permissions
Invalid key, expired token, incorrect signature, unauthorised role, blocked IP and reused nonce.
No response and unknown outcome
Connection failure before sending, after the operation is accepted and while receiving the final response.
Rate limiting
HTTP 429, recommended delay, concurrent requests and recovery after the limit expires.
Provider errors
Unavailability, maintenance, invalid response, delayed notification and conflicting status.
Retry and protective stop
Limiting attempt count, increasing delays, temporarily stopping requests, controlled recovery and manual escalation.
Pre-launch checklist
A production integration is launched after validating the error structure, client behaviour, duplicate protection and diagnostics.
All errors return a stable reason code and request identifier.
Error details do not expose secrets or internal implementation.
Temporary and permanent error categories are documented.
A retried critical operation uses the same idempotency key.
An unknown outcome is handled by checking state or receiving a trusted notification.
Logs, metrics, alerts, a recovery queue and escalation rules are configured.
Need to standardise API errors?
Send us your current HTTP responses, error codes, retry rules and problematic scenarios. APIACE will help define a unified error model, safe recovery and control approach.