Identity
Errors
Common error code values returned across Identity Verification endpoints.
Use this page to
- Look up what a
codein an error response means - Confirm whether a given failure charged your wallet
- Decide how to handle each error type in your integration
| Code | HTTP | Meaning | Charged? |
|---|---|---|---|
INVALID_REQUEST |
400 | Missing ID, or not 11 digits | No |
INSUFFICIENT_BALANCE |
400 | Wallet can't cover the per-call fee | No |
NOT_FOUND |
404 | No identity record for the supplied ID | No — auto-refunded if a debit occurred |
PROVIDER_ERROR |
502 | The verification provider was unreachable | No — auto-refunded |
SERVICE_UNAVAILABLE |
503 | This product isn't priced/enabled right now | No |
DEBIT_FAILED |
400 | Wallet debit could not be completed | No |
REQUEST_FAILED |
500 | Unexpected error; any debit is reversed | No |
Error shape
{
"status": "error",
"code": "INSUFFICIENT_BALANCE",
"message": "Your wallet balance is too low to cover this lookup."
}Handling recommendations
| Situation | Recommended handling |
|---|---|
INVALID_REQUEST |
Confirm the ID is exactly 11 digits before sending |
INSUFFICIENT_BALANCE |
Top up your NGN wallet before retrying |
NOT_FOUND |
The ID doesn't resolve to a record — confirm it with the customer rather than retrying blindly |
PROVIDER_ERROR |
Transient — retry after a short delay |
SERVICE_UNAVAILABLE |
This product isn't enabled for your business yet — contact support |
DEBIT_FAILED |
Transient — retry after a short delay |
REQUEST_FAILED |
Transient — retry after a short delay |
Billing guarantee: you are only ever charged when verified: true is returned. Every code in this table leaves your wallet whole — any debit that occurred before the failure is refunded automatically.
Questions? Email [email protected]. Also on GitBook.