Idempotency

All write endpoints in the Rekord API support the Idempotency-Key header to prevent duplicate operations on retry.

How it works

Include a unique string in the Idempotency-Key header with any write request:

curl -X POST "$REKORD_BASE_URL/contributions" \
  -H "Authorization: Bearer $REKORD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payslip-extract-2026-01-sarah-jones" \
  -d '{ ... }'

When the server receives a request with an idempotency key:

1. If the key has not been seen before, the request is processed normally and the response is cached.

2. If the key has been seen before, the server returns the cached response without reprocessing.

This makes retries safe — network timeouts, client crashes, or load balancer retries will not create duplicate resources.

Key format

The idempotency key is any unique string. Good patterns include:

• Source system identifier + event ID: revenue-integration-event-42

• Document ID + extraction version: payslip-doc-123-v2

• Client-generated UUID: 550e8400-e29b-41d4-a716-446655440000

Keys must be unique within your workspace. Reusing a key with a different request body returns the original cached response — it does not process the new body.

When to use idempotency keys

Idempotency keys are optional — the server does not reject requests that omit them. However, they are strongly recommended for:

• Contribution ingestion — duplicate contributions have compliance consequences

• Context creation — duplicate contexts create unnecessary decision boundaries

• Bulk operations — a timeout mid-batch should not create partial duplicates on retry

If you omit the idempotency key and a request times out, retrying the same request may create a duplicate resource. The server has no way to distinguish a retry from a genuinely new request.

Key expiry

Idempotency keys are retained for 24 hours. After expiry, a request with the same key is treated as new.

SDK behaviour

The Rekord SDK (when available) will auto-generate and send idempotency keys by default, so well-behaved clients get duplicate protection without explicit configuration.