> For the complete documentation index, see [llms.txt](https://docs.lumiid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumiid.com/api-integration/technical-references/lumiid-api-error-codes-and-http-response-handling.md). # LumiID API Error Codes and HTTP Response Handling ## LumiID API error codes and response handling Every LumiID API request returns a standard HTTP status code along with a JSON response body. Use both the HTTP status and the response payload to determine whether a request succeeded and how your application should respond to failures. *** ### API response format #### Successful response The request was successfully processed, and the verification completed successfully. Example response: ```json { "success": true, "code": "NIN_VERIFIED", "message": "NIN verification successful", "verification_type": "NIN", "summary": { "verified": true, "verification_type": "NIN", "provider": "LumiID", "confidence_score": 1.0 }, "data": { "...": "Verification data" }, "meta": { "request_id": "req_a3f9c21d9b4e", "timestamp": "2026-03-19T08:14:22.445821Z" } } ``` #### Failed verification response When a request cannot be completed, LumiID returns an appropriate HTTP status code with additional error details. ```json { "success": true, "code": "NIN_VERIFICATION_FAILED", "message": "Invalid NIN or verification failed", "verification_type": "NIN", "summary": { "verified": false, "verification_type": "NIN", "provider": "LumiID", "confidence_score": 0.0 }, "data": null, "meta": { "request_id": "req_b91d82fa13c4", "timestamp": "2026-03-19T08:15:11.902134Z" } } ``` Always check both the HTTP status code and the `summary.verified` field before processing the response. *** ### HTTP status codes #### 200 OK — Request successful Your request was processed successfully and the requested data has been returned. **Common scenarios** * Identity verification completed * Business verification completed * Data retrieved successfully *** ### API error codes | HTTP Status | Error Code | Cause | Recommended Action | | ----------- | ----------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **400** | **NIN\_VERIFICATION\_FAILED** | The NIN exists in the NIMC database but the verification process encountered an unexpected error. | Retry the request once. If the issue persists, contact LumiID Support and include the `request_id`. | | **400** | **NIN\_NOT\_FOUND** | No record was found for the supplied NIN. | Verify that the NIN contains exactly **11 digits** and check for transcription errors before retrying. | | **401** | **INVALID\_API\_KEY** | The API key is missing, invalid, malformed, or revoked. | Generate or copy a valid Secret Key from the LumiID Console and update your application. | | **401** | **UNAPPROVED\_ORGANIZATION** | Your organization has not yet been approved for production access. | Complete organization verification in the LumiID Console before using the Production API. | | **401** | **SUBSCRIPTION\_REQUIRED** | Your account is not subscribed to the requested verification service. | Enable the required verification service from the **Services** section of the LumiID Console. | | **402** | **INSUFFICIENT\_FUNDS** | Your wallet balance is insufficient to process the request. | Top up your LumiID wallet before retrying. | | **500** | **SERVER\_ERROR** | An unexpected internal error occurred while processing the request. | Retry once. If the issue continues, contact LumiID Support with the `request_id`. | | **503** | **SERVICE\_UNAVAILABLE** | LumiID could not establish a connection with the NIMC verification service. | Retry using exponential backoff. Check the LumiID Status Page for active incidents. | | **504** | **TIMEOUT** | The NIMC service did not respond within the expected time. | Wait a few seconds and retry the request. | *** ### Response metadata Every response includes metadata that can be used for logging, auditing, and troubleshooting. | Field | Description | | ------------ | ---------------------------------------------------------------------------------------------------- | | `request_id` | A unique identifier for the verification request. Include this value when contacting LumiID Support. | | `timestamp` | The ISO 8601 timestamp indicating when the request was processed. | Example: ``` { "meta": { "request_id": "req_a3f9c21d9b4e", "timestamp": "2026-03-19T08:14:22.445821Z" } } ``` *** ### Error-handling best practices To build resilient integrations with LumiID, we recommend the following: * Check the HTTP status and the `summary.verified` field. * Use `code` for application logic, not the `message`. * Log `request_id` and `customer_reference` securely for troubleshooting. * Retry temporary failures using exponential backoff. * Correct validation, authentication, and subscription errors before retrying. *** ### Troubleshoot an API error If you're unable to resolve an error: * Confirm you're using the correct environment (Sandbox or Production). * Verify your API credentials. * Review the endpoint documentation. * Include your **Customer Reference** or **Verification ID** when contacting LumiID Support for faster assistance. ### Related API guides * [API Keys and Authentication](/api-integration/technical-references/lumiid-api-authentication-or-api-keys-sandbox-and-production.md) * [NIN Verification API](/api-integration/government-verification/nin-verification-api-or-nigerian-national-id-lookup.md) * [BVN Verification API](/api-integration/government-verification/bvn-verification-api-or-nigerian-bank-verification-number-lookup.md) * [Identity Verification Glossary](/api-integration/technical-references/identity-verification-glossary-or-kyc-kyb-and-fraud-terms.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.lumiid.com/api-integration/technical-references/lumiid-api-error-codes-and-http-response-handling.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.