Errors

Handle every API error code and retry only when appropriate.

Transport or processing failures return a non-200 HTTP status and success: false.

Verification errors include a billing quote with charged: false. The amount is the price of the requested endpoint, not a debit. Balance endpoint errors omit the billing object.

Error catalog

HTTPCodeRetry automatically?
400INVALID_REQUESTNo, correct the request
400INVALID_IDEMPOTENCY_KEYNo, generate a valid key
401UNAUTHORIZEDNo, replace the key or scope
402INSUFFICIENT_BALANCENo, fund the wallet
409IDEMPOTENCY_KEY_REUSEDNo, use a new key for the new operation
409IDEMPOTENCY_IN_PROGRESSYes, after Retry-After
429RATE_LIMIT_EXCEEDEDYes, after Retry-After
500INTERNAL_ERRORYes, with the same idempotency key
503SERVICE_UNAVAILABLEYes, with backoff and the same key

The examples below use the ₦100 NIN Verification price. Other verification endpoints return their own price in billing.amount.

HTTP 400: invalid request

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "NIN must be 11 digits",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

HTTP 400: invalid idempotency key

{
  "success": false,
  "error": {
    "code": "INVALID_IDEMPOTENCY_KEY",
    "message": "Idempotency-Key must be 8 to 128 characters using letters, numbers, period, underscore, colon, or hyphen.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

HTTP 401: unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide a valid API key with the NIN_VERIFY scope.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

HTTP 402: insufficient balance

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your wallet balance is insufficient for this verification.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

HTTP 409: idempotency key reused

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "message": "This Idempotency-Key was already used with a different request.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

HTTP 409: idempotency request in progress

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_IN_PROGRESS",
    "message": "A request with this Idempotency-Key is still processing.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

The response includes Retry-After: 2.

HTTP 429: rate limit exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after the current rate limit window resets.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

Read the Retry-After and rate-limit headers before retrying.

HTTP 500: internal error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "The verification could not be completed.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

HTTP 503: service unavailable

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Verification service is temporarily unavailable, try again later.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "billing": {
    "amount": 100,
    "currency": "NGN",
    "unit": "naira",
    "charged": false,
    "note": "No charges"
  }
}

Retry guidance

Use the same idempotency key when retrying the same intended live verification. Apply exponential backoff with jitter for 500 and 503. Do not automatically retry validation, authentication, insufficient-balance, or idempotency-conflict responses without fixing their cause.

Include the response's X-Request-Id when contacting support.


Did this page help you?