---
title: "Idempotency and retries"
description: "What an idempotent request is, when it is safe to retry a call to Qomni and how to use the Idempotency-Key header."
version: "en"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency and retries

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:

```mermaid
sequenceDiagram
  participant S as Your server
  participant Q as Agents API
  S->>Q: POST /agents/v1/calls
  Q->>Q: creates call_01… and the agent dials
  Q--xS: the response is lost
  S->>Q: retry: POST /agents/v1/calls
  Q->>Q: creates call_02… and the agent dials again
  Q-->>S: 201 call_02…
```

1. Your server sends `POST /agents/v1/calls`.
2. Qomni creates the call and the agent dials the customer.
3. The response is lost along the way (the connection drops, your
   timeout expires).
4. Your code sees a network error and retries.
5. 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.

```bash
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" }'
```

```python
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,
)
```

```typescript
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.

> **Current status**
>
> The API accepts the `Idempotency-Key` header as the contract says, but
> deduplication is not active yet: today a retry creates a second
> resource. In the meantime, retry only when you know the request did not
> arrive (`503 origin_unavailable`, or a connection error before sending the
> body) and store the `id` of each response so you do not repeat an operation that
> already has a result.

## 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

- `GET` requests 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](/concepts/errors/): what each code means before deciding to retry.
- [Rate limits](/concepts/rate-limits/): the `Retry-After` of a `429`.
- [The edge and cells](/concepts/edge/): where a `origin_unavailable` comes from.

Source: https://docs.qomni.ai/concepts/idempotency/index.mdx
