LumiID API Error Codes and Response Handling Guide

Every LumiID API request returns a standard HTTP status code alongside a JSON response body. To correctly determine whether a request succeeded, you need to check both — the HTTP status tells you whether the request was received and processed, while the summary.verified field in the response body tells you whether the verification itself passed. Never rely on the HTTP status alone.

Response Structure

Successful Response

When a request is processed successfully and the verification completes, the API returns HTTP 200 OK with success: true and summary.verified: true.

{
  "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 verification cannot be completed — for example, a NIN that isn’t found — the API still returns HTTP 200 OK and success: true, but sets summary.verified to false and data to null.

{
  "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"
  }
}

Failed verifications (such as a NIN not found in the database) still return HTTP 200 with success: true. The distinction lies in summary.verified, which will be false. Always check summary.verified in addition to the HTTP status before processing a verification result.

Response Metadata

Every response includes a meta object with fields you can use for logging, auditing, and troubleshooting.

Field	Description
`request_id`	A unique identifier for the verification request. Include this value whenever you contact LumiID Support.
`timestamp`	An ISO 8601 UTC timestamp indicating when the request was processed.

Error Code Reference

The table below lists all error codes returned by the LumiID API, along with their causes and recommended actions.

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.

Best Practices

Following these guidelines will help you build a resilient, production-ready integration with LumiID:

Check both the HTTP status code and summary.verified. An HTTP 200 does not guarantee a successful verification — always read summary.verified before processing the result.
Use the code field for application logic, not message. The message field is human-readable and may change between releases. Your code should branch on code values, which are stable.
Log request_id and customer_reference securely. These values are essential for debugging and for getting faster resolutions when you contact LumiID Support.
Retry temporary failures with exponential backoff. Errors like 503 SERVICE_UNAVAILABLE and 504 TIMEOUT are transient. Implement a backoff strategy rather than retrying immediately.
Do not retry authentication or validation errors. Errors like INVALID_API_KEY, UNAPPROVED_ORGANIZATION, and SUBSCRIPTION_REQUIRED require a configuration fix — retrying without addressing the root cause will not help.
Add customer_reference to all production requests. A consistent reference value (such as your internal customer ID) makes it much easier to trace a specific request in your logs and in the LumiID Dashboard.

Get Started

General

Government Verification

Business Verification

Biometric & AML

SDKs & Integration

Reference

LumiID API Error Codes and Response Handling Guide

Response Structure

Successful Response

Failed Verification Response

Response Metadata

Error Code Reference

Best Practices

​Response Structure

​Successful Response

​Failed Verification Response

​Response Metadata

​Error Code Reference

​Best Practices

Response Structure

Successful Response

Failed Verification Response

Response Metadata

Error Code Reference

Best Practices