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ó:
- Tu servidor envía
POST /agents/v1/calls. - Qomni crea la llamada y el agente marca al cliente.
- La respuesta se pierde por el camino (se cae la conexión, se agota tu tiempo de espera).
- Tu código ve un error de red y reintenta.
- 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.
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" }),
});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.
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
GETya 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: qué significa cada código antes de decidir reintentar.
- Límites de uso: el
Retry-Afterde un429. - El edge y las celdas: de dónde sale un
origin_unavailable.