Idempotency - Lavendly

The contract

Send Idempotency-Key: <opaque-string> on a request that creates something or spends credits. Within 24 hours, a retry with the same key and the same body returns the same status code and body, byte for byte, with an Idempotent-Replay: true header. Nothing runs again and nothing is charged again.

Still running: a retry while the first request is in progress gets 409 idempotency_in_flight. Wait and retry; never run a second copy.
Same key, different body: 422 idempotency_key_reuse. A key binds to one payload.
Keys are scoped to your account, so two accounts sending the same key never collide.

Where it applies

Endpoint	Replay window
`POST /v1/workflows`	24 hours
`POST /v1/workflows/{id}/generate`	24 hours
`POST /v1/workflows/{id}/renders`	24 hours
`POST /v1/workflows/{id}/finalize`	24 hours
`POST /v1/videos`	24 hours
`POST /v1/chat/completions` (images)	24 hours
`POST /v1/audio/speech`	24 hours
`POST /v1/audio/music`	24 hours
`POST /v1/workflows/{id}/clips/{clip_id}/tracks`	5 minutes

Use it whenever the same logical action might fire twice: network retries, double clicks, agent tool calls that time out.

Pattern: generate the key once

// Bad: a new key every attempt means a retry is a second, paid request.
const key = `render-${Date.now()}`;

// Good: one key per logical action, reused on every retry of it.
const key = `render-${workflow_id}-${attempt_group}`;

For agents, ${tool_name}-${workflow_id}-${YYYY-MM-DD} collapses the same request on the same day into one run.

After the window

A retry after the window does run again (and is charged again). Design for that: keep the key with the job you started and check its status before retrying.