---
title: "Idempotencia y reintentos"
description: "Qué es una petición idempotente, cuándo es seguro reintentar una llamada a Qomni y cómo usar el header Idempotency-Key."
version: "es"
---

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

# Idempotencia y reintentos

Una petición es **idempotente** cuando repetirla produce el mismo resultado
que hacerla una sola vez. Listar tus llamadas es idempotente: lo haces diez
veces y la lista no cambia. Crear una llamada no lo es: la creas dos veces y
el agente marca dos veces al mismo cliente.

Las redes fallan, así que tu código tiene que reintentar. El problema es
reintentar una petición que crea algo sin crearlo dos veces.

## Por qué el problema existe

El caso peligroso no es cuando la petición falla. Es cuando no sabes si falló:

```mermaid
sequenceDiagram
  participant S as Tu servidor
  participant Q as Agents API
  S->>Q: POST /agents/v1/calls
  Q->>Q: crea call_01… y el agente marca
  Q--xS: la respuesta se pierde
  S->>Q: reintento: POST /agents/v1/calls
  Q->>Q: crea call_02… y el agente marca otra vez
  Q-->>S: 201 call_02…
```

1. Tu servidor envía `POST /agents/v1/calls`.
2. Qomni crea la llamada y el agente marca al cliente.
3. La respuesta se pierde por el camino (se cae la conexión, se agota tu
   tiempo de espera).
4. Tu código ve un error de red y reintenta.
5. Qomni crea una segunda llamada y el cliente recibe dos.

Desde tu lado, los pasos 2 y 3 son invisibles: un fallo de red antes de la
respuesta se ve igual que un fallo de red antes de que la petición llegara.
Ningún cliente puede distinguirlos solo.

## Cómo se resuelve

La solución es que tú nombres cada operación. Envías un header
`Idempotency-Key` con un valor que eliges, y repites ese mismo valor en cada
reintento de la misma operación. Así la API puede reconocer el reintento y
devolver el resultado de la primera vez en lugar de crear otra llamada.

```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" }),
});
```

La clave buena sale de tus propios datos: el id del pedido que se recuerda,
el id de la cita que se confirma, el id del cliente más la fecha. Una clave
aleatoria generada en cada reintento no sirve, porque cada reintento llevaría
una clave nueva.

> **Estado actual**
>
> La API acepta el header `Idempotency-Key` según el contrato, pero la
> deduplicación todavía no está activa: hoy un reintento crea un segundo
> recurso. Mientras tanto, reintenta sólo cuando sepas que la petición no
> llegó (`503 origin_unavailable`, o un error de conexión antes de enviar el
> cuerpo) y guarda el `id` de cada respuesta para no repetir una operación que
> ya tiene resultado.

## Cuándo reintentar

| Qué recibiste | Reintenta | Por qué |
|---|---|---|
| `503 origin_unavailable` | Sí, con backoff | La celda no recibió la petición. No se hizo nada. |
| `429 rate_limited` | Sí, tras `Retry-After` segundos | La petición no se procesó. |
| Error de conexión antes de enviar el cuerpo | Sí | La petición no llegó. |
| Tiempo de espera agotado esperando la respuesta | Sólo con `Idempotency-Key` | Puede haber llegado y haberse procesado. |
| `4xx` distinto de `429` | No | La petición está mal. Reintentarla igual fallará igual. |

Usa un **backoff exponencial**: espera 1 segundo, luego 2, luego 4, con un
máximo de cinco intentos. Reintentar sin esperar sólo empeora una celda que ya
está saturada.

## Límites

- Las peticiones `GET` ya son idempotentes. No necesitan el header.
- La clave identifica una operación, no un recurso. Dos pedidos distintos
  llevan dos claves distintas aunque llamen al mismo número.
- La clave no cambia lo que hace la petición. Si reintentas con la misma
  clave y otro cuerpo, el cuerpo que cuenta es el de la primera vez.

## Ver también

- [Errores](/es/concepts/errors/): qué significa cada código antes de decidir reintentar.
- [Límites de uso](/es/concepts/rate-limits/): el `Retry-After` de un `429`.
- [El edge y las celdas](/es/concepts/edge/): de dónde sale un `origin_unavailable`.

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