Idempotency and Retries

Prevent duplicate live lookups and wallet charges during retries.

Every verification request requires an Idempotency-Key header.

Why it matters

Network timeouts can leave a client uncertain whether a live request completed. Idempotency lets the client retry the same intended verification without a second live lookup or wallet charge.

Key format

A key must:

  • Contain 8 to 128 characters.
  • Use only letters, numbers, periods, underscores, colons, or hyphens.
  • Be unique for each intended verification.

Valid examples:

customer-123-verification-001
req_550e8400-e29b-41d4-a716-446655440000
order:9842:identity-check

Replay behavior

For live requests:

  • Same key and same normalized body: the stored response is returned.
  • Replayed responses include Idempotency-Replayed: true.
  • No second live lookup is performed.
  • The wallet is not charged again.
  • Records are retained for 24 hours.

Conflict behavior

Reusing a key with a different request body returns:

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

A concurrent duplicate returns IDEMPOTENCY_IN_PROGRESS with Retry-After: 2.

Sandbox behavior

Test requests must include a valid header, but sandbox idempotency records are not persisted. Use sandbox values to test response handling, then validate replay behavior with controlled live requests.

Recommended implementation

Generate the key on your server when the business operation is created, store it with that operation, and reuse it for every retry of the same verification.


Did this page help you?