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: process_claim_12345_doc_1

{
  "idempotency_key": "process_claim_12345_doc_1"
}

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.

{
  "case_id": "case_abc123",
  "doc_id": "doc_def456",
  "job_id": "job_ghi789",
  "status": "queued",
  "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.