# Idempotency
Safely retry session creation, document processing, and webhook acknowledgement requests
Source: https://www.klarefi.com/docs/api/idempotency

Use idempotency when retrying API calls after timeouts or network errors.

`POST /api/v1/sessions` and `POST /api/v1/process` require an idempotency key.
Send it in either place:

```http
Idempotency-Key: session_claim_12345
```

```json
{
  "idempotency_key": "session_claim_12345"
}
```

If both are present, the JSON body value wins.

## Replays

Repeating the same request with the same key returns the original resource with
HTTP `200` and `idempotent_replay: true`.

```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "signed_url": "https://app.klarefi.com/s/550e8400...?token=...",
  "expires_at": "2026-01-22T10:30:00.000Z",
  "idempotent_replay": true
}
```

## Conflicts

Reusing an idempotency key with different request parameters returns a
validation error:

```json
{
  "error": {
    "type": "validation_error",
    "code": "idempotency_key_conflict",
    "message": "idempotency_key was already used with different request parameters",
    "request_id": "req_abc123def456"
  }
}
```

## Webhook acknowledgements

`POST /api/v1/webhooks/deliveries/\{deliveryId\}/ack` accepts an optional
`acknowledgement_id` body field. If it is omitted, Klarefi uses the
`Idempotency-Key` header when present.