Response Codes & Statuses
Custom Response Codes (HTTP 200)
These custom codes appear in the response_code field of the JSON body, even when the standard HTTP status is 200 OK. It is important to note that custom response codes complement the standard HTTP response.
| Response Code | Meaning | Explanation | Recommended Action | Applicable Endpoints |
|---|---|---|---|---|
00 | Successful | The request was processed and the expected data has been returned. | No action needed. Process data returned. | All Endpoints |
01 | Record Not Found | The ID provided in the request was not found in the system or may be incorrect. | Validate ID details and resubmit. Notify end-user if persistent. | All ID-verification endpoints |
02 | Unavailable | The requested service is currently unavailable (e.g., maintenance, downtime). | Retry after a delay. Implement exponential back-off. | All endpoints |
03 | Insufficient Balance | Insufficient wallet balance to complete the requested transaction. | Top up wallet balance and retry. | All endpoints |
07 | Blocked / Watchlisted | Indicates that the provided BVN has been blocked or watchlisted. | Do not retry with the same BVN. Escalate if required. | BVN endpoint only |
Verification Statuses
Verification Status is used to indicate the current state of a verification request. There are three possible values:
| Verification Status | Explanation |
|---|---|
PENDING | The verification request has failed internally and will be retried at a later time. |
NOT-VERIFIED | The verification request was successfully performed, but the ID provided is not valid. |
VERIFIED | The verification request was successfully performed, and the ID provided is valid. |
Response Structure Examples
Record Not Found (01)
{
"status": false,
"response_code": "01",
"message": "Record not found.\nThe ID data you entered does not exist or may be incorrect. Please ensure all details are correct and resubmit.",
"verification": {
"reference": "254d1801-db5d-450a-954b-3682ddae7072"
},
"session": {}
}Service Unavailable (02)
{
"status": false,
"detail": "Verification failed",
"response_code": "02",
"message": "Verification can't be completed at this time. Kindly retry later",
"verification": {
"reference": ""
},
"session": {}
}Insufficient Balance (03)
{
"status": false,
"response_code": "03",
"detail": "Insufficient wallet balance",
"verification": {
"reference": "ca97b55e-880d-4e37-8e29-1529c3ffe9e6"
},
"session": {}
}