Errors
Handle every API error code and retry only when appropriate.
Transport or processing failures return a non-200 HTTP status and success: false.
Verification errors include a billing quote with charged: false. The amount is the price of the requested endpoint, not a debit. Balance endpoint errors omit the billing object.
Error catalog
| HTTP | Code | Retry automatically? |
|---|---|---|
400 | INVALID_REQUEST | No, correct the request |
400 | INVALID_IDEMPOTENCY_KEY | No, generate a valid key |
401 | UNAUTHORIZED | No, replace the key or scope |
402 | INSUFFICIENT_BALANCE | No, fund the wallet |
409 | IDEMPOTENCY_KEY_REUSED | No, use a new key for the new operation |
409 | IDEMPOTENCY_IN_PROGRESS | Yes, after Retry-After |
429 | RATE_LIMIT_EXCEEDED | Yes, after Retry-After |
500 | INTERNAL_ERROR | Yes, with the same idempotency key |
503 | SERVICE_UNAVAILABLE | Yes, with backoff and the same key |
The examples below use the ₦100 NIN Verification price. Other verification endpoints return their own price in billing.amount.
HTTP 400: invalid request
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "NIN must be 11 digits",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}HTTP 400: invalid idempotency key
{
"success": false,
"error": {
"code": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be 8 to 128 characters using letters, numbers, period, underscore, colon, or hyphen.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}HTTP 401: unauthorized
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Provide a valid API key with the NIN_VERIFY scope.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}HTTP 402: insufficient balance
{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Your wallet balance is insufficient for this verification.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}HTTP 409: idempotency key reused
{
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}HTTP 409: idempotency request in progress
{
"success": false,
"error": {
"code": "IDEMPOTENCY_IN_PROGRESS",
"message": "A request with this Idempotency-Key is still processing.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}The response includes Retry-After: 2.
HTTP 429: rate limit exceeded
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Retry after the current rate limit window resets.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}Read the Retry-After and rate-limit headers before retrying.
HTTP 500: internal error
{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "The verification could not be completed.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}HTTP 503: service unavailable
{
"success": false,
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "Verification service is temporarily unavailable, try again later.",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
},
"billing": {
"amount": 100,
"currency": "NGN",
"unit": "naira",
"charged": false,
"note": "No charges"
}
}Retry guidance
Use the same idempotency key when retrying the same intended live verification. Apply exponential backoff with jitter for 500 and 503. Do not automatically retry validation, authentication, insufficient-balance, or idempotency-conflict responses without fixing their cause.
Include the response's X-Request-Id when contacting support.
Updated about 2 hours ago