Idempotency

Networks fail mid-request. When they do, you want to retry without risking a second flow run or a duplicate charge. Send an Idempotency-Key header and a retry replays the original response instead of re-executing.

How it works

Generate a unique key per logical operation (a UUID is fine) and send it on the request:

curl -X POST https://api.zerowidth.ai/1.0/flows/<flowUuid>/runs \
  -H "Authorization: Bearer zw_live_…" \
  -H "Idempotency-Key: 3f9a1c7e-…" \
  -H "Content-Type: application/json" \
  -d '{"input":{"kind":"form","values":{"data":"hello"}}}'

Same key, same request body → the stored status and body are replayed verbatim. The work runs only once.
Same key, different body → 409 conflict. A key is bound to the exact request it first saw, so you can't accidentally reuse one for a different call.
No header → no idempotency; the request runs normally.

Details worth knowing

Window: keys are remembered for 24 hours. After that the same key is treated as new.
Scope: keys are scoped to the credential that sent them — your key can't collide with another customer's.
Only successful and client-error responses are stored. A 5xx is not cached, so retrying after a server error genuinely re-runs the request rather than replaying the failure.
Streaming runs aren't cached — an SSE (stream: true) response can't be replayed; send a fresh request.

Where it's honored

The mutating POST endpoints accept Idempotency-Key:

2 min read