Reference
Errors & status codes
Century returns a consistent error envelope. Read the code, not the message — messages are written for humans and may change.
Envelope
Error response
{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient wallet balance.",
"request_id": "req_xxxxxxxxx"
}
}Server failures also carry an error ID that support can trace to a structured log entry. Surface it to your users when you show a failure screen.
Codes
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | UNAUTHORIZED | Missing, expired or invalid bearer token. | Refresh the session and retry once. |
| 403 | FORBIDDEN | Authenticated, but the account is not allowed to perform this action. | Do not retry; the caller lacks the role. |
| 403 | KYC_REQUIRED | The action needs a higher KYC tier than the account holds. | Send the user through the required tier, then retry. |
| 400 | VALIDATION_FAILED | The request body did not match the schema (wrong type, missing field, out-of-range amount). | Fix the payload; retrying unchanged will fail again. |
| 400 | NETWORK_MISMATCH | The recipient number does not belong to the selected network. | Correct the network or the phone number. |
| 400 | INVALID_PIN | The 4-digit transaction PIN was wrong or is not set. | Re-prompt for the PIN. Repeated failures lock the PIN temporarily. |
| 402 | INSUFFICIENT_BALANCE | The wallet cannot cover the amount plus fees. | Ask the user to fund the wallet, then retry. |
| 404 | NOT_FOUND | The referenced transaction, order or reference does not exist for this caller. | Check the identifier; do not retry blindly. |
| 409 | DUPLICATE_REQUEST | A request with the same reference/idempotency key was already processed. | Treat as success and read the original result. |
| 422 | PROVIDER_REJECTED | The upstream provider declined the order (bad plan, closed account, biller down). | The wallet is refunded automatically. Surface the message and let the user retry or pick another plan. |
| 424 | PROVIDER_UNAVAILABLE | The upstream provider is unreachable or returned a 5xx. | Retry with backoff; Century may auto-swap to an equivalent plan. |
| 429 | RATE_LIMITED | Too many requests from this account or IP in a short window. | Back off and retry after the cooldown. |
| 500 | SERVER_ERROR | Unexpected failure. Logged with an error ID. | Retry once; if it persists, contact support with the error ID. |
Retry policy
- 401 — refresh the token, retry once.
- 429, 424, 500 — retry with exponential backoff and jitter, max 3 attempts.
- 400, 402, 403, 404, 422 — never retry unchanged.
- 409 — the original request already succeeded; read the result instead of retrying.
Never blind-retry a purchase
A purchase that returns a timeout may still have been fulfilled. Poll the transaction by its reference before issuing another one, otherwise you risk double-spending the user's wallet.