IN
INFYNIA

Idempotency

Retry a POST safely with the Idempotency-Key header, and what happens when a key is reused.

Why

If a network error hides the answer to a POST, you do not know whether the call was placed. Resending it blindly could call someone twice. With an idempotency key, the retry returns the first answer instead of doing the work again.

How

  • Send an Idempotency-Key header (1 to 255 characters) on any POST. Use a value tied to your own business event, such as an order identifier, or a random UUID stored with the operation.
  • For 24 hours, a request with the same key, the same route and the same body returns the status and body of the first one, with the header Idempotent-Replayed: true.
  • The same key with another body or another route answers 422 with idempotency_mismatch.
  • Only successful answers (2xx) are stored. An error (4xx, 5xx, 429) is never stored and releases the key: fix the cause (agent inactive, call outside hours...) and retry with the same key, the request really runs again.
  • A key outside 1 to 255 characters answers 400 with invalid_idempotency_key.
# Same key, same body: the first response is replayed (Idempotent-Replayed: true)
curl -i -X POST https://infynia.quantylcore.com/api/v1/calls \
  -H "Authorization: Bearer $INFYNIA_API_KEY" \
  -H "Idempotency-Key: order-1042-callback" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "AGENT_ID", "to": "+15555550100"}'

Two requests with the same key sent at the same time are serialized: the second one answers 409 with idempotency_in_progress while the first one runs. Wait, then resend: you get the stored answer. The key is scoped to the API key and its mode: the same value used with another key, or with a test key and a live key, never shares an answer.

The idempotencyKey field of POST /v1/calls

The body of POST /v1/calls also accepts an idempotencyKey field. It is a separate mechanism that deduplicates calls over time: when a call with the same value already exists, the answer is 200 with duplicate: true. Use the header for safe retries and the body field if you want the call itself to be unique.