API REFERENCE
Errors & idempotency
Handle uncertainty without double purchases or duplicate actions.
HTTP status codes
| Status | Meaning | Client action |
|---|---|---|
| 400 | Invalid body or arguments | Correct input |
| 401 | Missing, expired or revoked credential | Reauthenticate securely |
| 403 | Missing scope or ownership/role permission | Use the authorized account and scope |
| 404 | Route/resource unavailable | Check API version and identifiers |
| 409 | Conflict, stock or state issue | Read current state before deciding |
| 429 | Rate limit | Back off and avoid repeated login attempts |
| 500 | Request could not complete | Treat mutations as uncertain; reconcile |
| 503 | Closed service gate or provider uncertainty | Check service/operation state before retrying |
Stable keys
Purchase, top-up and refund creation use an Idempotency-Key. Create it once for the user's intended operation and preserve it across network retries. A new key means a new request, not a retry.
Read after uncertainty
If a request times out, query the account or operation state before issuing another mutation. The controller might have completed an action even though its response was lost. Do not retry a desktop click blindly when it could submit an order or send a message.
Errors are deliberately limited
The service does not echo credentials, provider response bodies or internal controller addresses in public errors. Record your own safe correlation identifier without copying a bearer token or customer screen into logs.