> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Idempotency

> Making safe, retryable POST requests with idempotency keys.

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:

```bash
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`:

```json
{
  "error": "idempotency_mismatch",
  "detail": "Idempotency key has already been used with different parameters.",
  "status_code": 422
}
```

## 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](/best-practices/preventing-duplicates) — Broader deduplication
  strategies
* [Errors](/api-details/errors) — 422 idempotency mismatch error details
* [Sessions](/core-concepts/sessions) — Session creation with idempotency