Prembly API – Response Codes & Verification Status
Client Documentation · HTTP & Custom Response Codes · Prepared for Client Reference
| HTTP Code | Category | Meaning / Short Label | Explanation | Example Response Body | Notes | Custom Code |
|---|---|---|---|---|---|---|
| 200 | 2XX | OK / Successful | The request was successful and the expected data has been returned. | {"status": true, "response_code": "00", "data": { ... }} | Standard success. Check response_code field for Prembly-specific status. | 00 |
| 200 | 2XX | Record Not Found (Soft) | Request succeeded at HTTP level but the ID was not found or may be incorrect in the Prembly system. | {"status": true, "response_code": "01", "message": "Record not found"} | Prembly returns HTTP 200 even when a record is not found. Check response_code. | 01 |
| 200 | 2XX | Service Unavailable (Soft) | Verification cannot be completed at this time. The service may be under maintenance or temporarily down. | {"status": true, "response_code": "02", "message": "Verification can't be completed, retry later"} | Retry with exponential back-off. Monitor Prembly status page. | 02 |
| 200 | 2XX | Insufficient Wallet Balance | There is insufficient balance in the wallet to complete the transaction. | {"status": false, "response_code": "03", "message": "Insufficient wallet balance"} | Top up wallet before retrying. | 03 |
| 200 | 2XX | Blocked / Watch-listed | Applicable to the BVN endpoint. The BVN provided has been flagged/blocked. | {"status": false, "response_code": "07", "message": "BVN is blocked/watch-listed"} | BVN-specific. Do not retry with same BVN. | 07 |
| 400 | 4XX | Bad Request | The request was malformed or missing required parameters. | {"status": false, "message": "Bad request: missing required field 'id_number'"} | Validate all required fields before sending. | - |
| 401 | 4XX | Unauthorized | Authentication credentials are missing or invalid. | {"status": false, "message": "Unauthorized: invalid API key"} | Verify API key is correctly set in the Authorization header. | - |
| 403 | 4XX | Forbidden | The authenticated client does not have permission to access this resource or endpoint. | {"status": false, "message": "Forbidden: you do not have access to this resource"} | Contact Prembly support if access should be granted. | - |
| 404 | 4XX | Not Found | The requested endpoint or resource does not exist. | {"status": false, "message": "Not found: endpoint does not exist"} | Verify the endpoint URL against the latest API documentation. | - |
| 405 | 4XX | Method Not Allowed | The HTTP method used (e.g., GET vs POST) is not supported for this endpoint. | {"status": false, "message": "Method not allowed"} | Check API docs for the required HTTP method per endpoint. | - |
| 422 | 4XX | Unprocessable Entity | The request was well-formed but contained semantic errors (e.g., invalid ID format). | {"status": false, "message": "Validation error: id_number must be numeric"} | Review field formats and constraints in the API docs. | - |
| 429 | 4XX | Too Many Requests | Rate limit exceeded. The client has sent too many requests in a given time window. | {"status": false, "message": "Rate limit exceeded. Try again in 60 seconds."} | Implement rate-limiting logic and exponential back-off on the client side. | - |
| 500 | 5XX | Internal Server Error | An unexpected error occurred on the Prembly server side. | {"status": false, "message": "Internal server error. Please try again later."} | Log the request ID and contact Prembly support if persistent. | - |
| 502 | 5XX | Bad Gateway | Prembly's server received an invalid response from an upstream service. | {"status": false, "message": "Bad gateway"} | Usually transient. Retry after a short delay. | - |
| 503 | 5XX | Service Unavailable | The server is temporarily unable to handle requests (overload or maintenance). | {"status": false, "message": "Service temporarily unavailable"} | Check Prembly status page. Retry with back-off. | - |
| 504 | 5XX | Gateway Timeout | The upstream service did not respond in time. | {"status": false, "message": "Gateway timeout"} | Retry after delay. If frequent, report to Prembly. | - |
Updated about 7 hours ago