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:

Idempotency-Key: session_claim_12345

{
  "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.

{
  "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:

{
  "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.