Idempotency

Networks drop responses. An Idempotency-Key lets you retry a POST without creating a second project, starting a second transcription or rendering (and paying for) the same exports twice.

How it works

Send a unique value (a UUID is ideal, up to 200 characters) in the Idempotency-Key header. The first request runs normally and its response is stored for 24 hours. A retry with the same key and the same body gets that stored response back, with Idempotent-Replayed: true, and nothing runs again.

shell

KEY=$(uuidgen)   # generate once per logical operation, reuse it for every retry

curl -X POST https://capxion.me/api/v1/projects/$PROJECT_ID/exports \
  -H "Authorization: Bearer $SPEAK_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{ "presets": ["instagram_reels"] }'

Supported endpoints

Endpoint	Why it matters
`POST /projects`	Creates a project and may start an import or transcription
`POST /projects/{project_id}/transcribe`	Charges transcription credits
`POST /projects/{project_id}/exports`	Queues renders that charge credits

GET, PUT and DELETE requests are naturally safe to repeat. Keys are scoped to your account, so two accounts can never collide.

Edge cases

Situation	Response
Same key, same body, first request finished	The stored response (status and body), Idempotent-Replayed: true
Same key, different body or endpoint	422 invalid_request, param Idempotency-Key
Same key while the first request is still running	409 conflict; retry shortly
The first request failed with a 5xx	Not stored: the retry runs again
The first request failed with a 4xx	Stored and replayed: fix the request and use a new key
Key older than 24 hours	Treated as new