# Errors & idempotency

Handle uncertainty without double purchases or duplicate actions.

Status: Implemented management conventions

## 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.