> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumiid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LumiID API Error Codes and Response Handling Guide

> Complete reference for LumiID API error codes, HTTP status codes, and response handling. Includes retry guidance and best practices for integrations.

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`.

```json theme={null}
{
  "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`.

```json theme={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"
  }
}
```

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.