Idempotency

POST endpoints support idempotent requests using the Idempotency-Key header. This lets you safely retry requests without creating duplicate resources.

Usage

Pass a unique key (up to 255 characters) in the Idempotency-Key header:

$
curl -X POST https://api.withverifa.com/api/v1/sessions \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Idempotency-Key: req_abc123_attempt_1" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "external_ref": "user_abc123",
>
    "country": "US"
>
  }'

If you send the same Idempotency-Key with the same parameters within the cache window, Verifa returns the original response without creating a new resource.

Cache duration

Idempotency keys are cached for 24 hours from the first request. After 24 hours, the key expires and the same value can be reused.

Parameter mismatch

If you send the same Idempotency-Key with different request parameters, the API returns 422 Unprocessable Entity:

1
{
2
  "error": "idempotency_mismatch",
3
  "detail": "Idempotency key has already been used with different parameters.",
4
  "status_code": 422
5
}

Supported endpoints

Idempotency keys are supported on the following POST endpoints:

• POST /api/v1/sessions
• POST /api/v1/sessions/bulk-redact
• POST /api/v1/webhooks/endpoints/{endpoint_id}/test

Key generation tips

Use a value that uniquely identifies the intent of the request:

• Transaction ID: txn_12345
• User action + timestamp: signup_user_abc_1738368000
• UUID: 550e8400-e29b-41d4-a716-446655440000

Avoid using values that change across retries (like random values generated on each attempt).

Related

• Preventing Duplicates — Broader deduplication strategies
• Errors — 422 idempotency mismatch error details
• Sessions — Session creation with idempotency