A request is idempotent when repeating it produces the same result as making it once. Listing your calls is idempotent: do it ten times and the list does not change. Creating a call is not: create it twice and the agent dials the same customer twice.
Networks fail, so your code has to retry. The problem is retrying a request that creates something without creating it twice.
Why the problem exists
The dangerous case is not when the request fails. It is when you do not know whether it failed:
- Your server sends
POST /agents/v1/calls. - Qomni creates the call and the agent dials the customer.
- The response is lost along the way (the connection drops, your timeout expires).
- Your code sees a network error and retries.
- Qomni creates a second call and the customer receives two.
From your side, steps 2 and 3 are invisible: a network failure before the response looks the same as a network failure before the request arrived. No client can tell them apart on its own.
How it is solved
The solution is that you name each operation. You send an
Idempotency-Key header with a value you choose, and repeat that same value on every
retry of the same operation. That way the API can recognize the retry and
return the first result instead of creating another call.
curl https://api.qomni.ai/agents/v1/calls \
-H "Authorization: Bearer $QOMNI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-reminder" \
-d '{ "to": "+15005550001" }'import os
import requests
key = os.environ["QOMNI_KEY"]
response = requests.post(
"https://api.qomni.ai/agents/v1/calls",
headers={
"Authorization": f"Bearer {key}",
"Idempotency-Key": "order-1042-reminder",
},
json={"to": "+15005550001"},
timeout=10,
)const response = await fetch("https://api.qomni.ai/agents/v1/calls", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.QOMNI_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "order-1042-reminder",
},
body: JSON.stringify({ to: "+15005550001" }),
});A good key comes from your own data: the id of the order being reminded about, the id of the appointment being confirmed, the customer id plus the date. A random key generated on each retry is useless, because each retry would carry a new key.
When to retry
| What you got | Retry | Why |
|---|---|---|
503 origin_unavailable |
Yes, with backoff | The cell did not receive the request. Nothing happened. |
429 rate_limited |
Yes, after Retry-After seconds |
The request was not processed. |
| Connection error before sending the body | Yes | The request did not arrive. |
| Timeout while waiting for the response | Only with Idempotency-Key |
It may have arrived and been processed. |
4xx other than 429 |
No | The request is wrong. Retrying it as is will fail the same way. |
Use exponential backoff: wait 1 second, then 2, then 4, with a maximum of five attempts. Retrying without waiting only makes a cell that is already saturated worse.
Limits
GETrequests are already idempotent. They do not need the header.- The key identifies an operation, not a resource. Two different orders carry two different keys even if they call the same number.
- The key does not change what the request does. If you retry with the same key and a different body, the body that counts is the first one.
See also
- Errors: what each code means before deciding to retry.
- Rate limits: the
Retry-Afterof a429. - The edge and cells: where a
origin_unavailablecomes from.