Error reference

All errors follow the same shape:

{ "detail": "Human-readable description of what went wrong" }

The HTTP status code is the primary signal; the detail string is for human diagnostics.

By status code

400 Bad Request

The request failed validation, either at our boundary or upstream at NIMC.

detail substring	Likely cause	Action
requestReason / Invalid requestReason	You passed the human label instead of the key, or the reason is not allowed for this endpoint	Fetch fresh keys from /nimc-reasons and pass key. For demography, use nyscCheck.
must be 11 digits	NIN or phone number is malformed	Strip non-digits, confirm length.
must be in dd-mm-yyyy	DOB format wrong on demography	Convert to dd-mm-yyyy (e.g. 03-09-1999).
Verification failed	NIMC rejected the lookup (most often “no record found”)	Try a different mode or confirm the data with the holder.

401 Unauthorized

Token is missing, expired (>60 min old), or revoked. Re-login.

402 Payment Required

Your wallet has no units. Top up before retrying. See Wallet & units.

The platform may also return 402 Active subscription required for verification if your org’s yearly subscription has expired. Contact support to renew.

403 Forbidden

The token is valid but the user lacks permission for this action. The most common cause: the user does not have the IDENTITY role. Have a platform admin enable it on the user.

404 Not Found

Returned by /verify-nin/requery when no matching record exists. Confirm the reference_id is correct and was generated against this org.

422 Unprocessable Entity

Pydantic-level validation failure — your JSON body is structurally wrong (missing required field, wrong type). The detail array names each offending field.

{
  "detail": [
    { "loc": ["body", "nin"], "msg": "field required", "type": "value_error.missing" }
  ]
}

429 Too Many Requests

You hit the rate limit. Back off and retry. See Rate limits.

5xx

A server-side or upstream problem. Retry with exponential backoff (start at 1s, double up to 30s, cap at 5 retries). If it persists after a few minutes, contact support with:

1. The request’s reference_id (if a verification call was attempted)
2. The exact request body (with the NIN/phone redacted)
3. The exact response body and HTTP status

Idempotency on failure

Failed verifications never debit your wallet. You can retry safely without losing units. Re-queries are similarly free.

The only edge case: in-person verifications where NIMC’s face match returns “below threshold” technically completed an upstream lookup — RandaVerify still records the call in your audit log but does not debit the wallet.