When to use it

Use Idempotency-Key on POST /v1/runs whenever your client may retry after a network timeout, 5xx, worker restart, queue redelivery, or uncertain response. The key lets Semarize recognize the same logical run creation attempt.

Generate one key for one logical run creation request.
Reuse that same key only when retrying the same request.
Do not reuse the key for a different conversation, Kit, workspace, or request body.

Key design

Prefer deterministic keys from your own durable identifiers. That makes queue retries, replay jobs, and crash recovery easier because the same work item naturally produces the same idempotency key.

Example key formats

crm-sync:deal_123:call_456:kit_A1B2C3D4
ticket-review:ticket_987:message_654:kit_SUPPORT_QA
batch_2026_06_16:row_000182:kit_A1B2C3D4

Retry flow

Situation	Client behavior
Request timed out before a response	Retry POST /v1/runs with the same Idempotency-Key and the same body.
Response was 202	Persist run_id, then poll GET /v1/runs/{runId}. Do not create another run.
Response was 429	Wait for Retry-After or retry_after_seconds, then retry with the same key if the run was not created.
Response was 409	Treat the key as already used for a conflicting request. Generate a new key only after confirming the new request is intentional.

Conflict handling

A 409 conflict means the idempotency key no longer represents a safe duplicate of the original logical request. This commonly happens when the same key is reused with a different body or target. Log the key, request fingerprint, and upstream work item before retrying.

Do not solve 409 by automatically generating a new key in a blind retry loop. That can turn a duplicate-prevention signal into duplicate run creation.

Scope and storage

Keep the idempotency key next to the upstream job record that created the run. Store the Semarize run_id once a run is accepted so later retries can skip creation and poll the existing run.

Store key, run_id, Kit identifier, source record id, and request timestamp.
Record the final run status and terminal error fields for replay decisions.
Use separate keys for sandbox/test workflows and production workflows.

Related guides

Async runs

Create runs, poll safely, handle sync fallback, and use webhooks for terminal events.

Errors

Map HTTP status codes, flat error envelopes, and terminal run failure fields.

Rate limits

Respect Retry-After, slow polling loops, and build controlled batch workers.

Versioning

Understand /v1 stability, additive changes, and Kit version pinning.

Status

Use status signals, incident retry behavior, and escalation details in production.