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-checkReplay 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.
Updated about 2 hours ago