Idempotencia
Cómo reintentar una acción o un POST sin crear ni cobrar dos veces, con el header Idempotency-Key.
Una red falla en el peor momento: mandaste POST /actions/create_lead, la conexión se cortó y no sabes si la empresa se creó. Con el header Idempotency-Key puedes reintentar sin miedo: si el primer pedido llegó a ejecutarse, el reintento te devuelve su respuesta en vez de crear la empresa (o cobrar una búsqueda) otra vez.
Cómo se usa
Genera un valor único por operación (un UUID es lo más simple) y mándalo en el header. Si tienes que reintentar esa misma operación, manda el mismo valor y exactamente el mismo cuerpo.
curl -X POST https://app.reclee.com/api/v1/actions/create_lead \
-H "Authorization: Bearer $RECLEE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6d1f0c3a-8b2e-4f7d-9a5c-3e4b2d1c0f9a" \
-d '{"name":"Nimbus Logistics","source":"REFERRAL"}'El valor tiene que tener entre 1 y 255 caracteres ASCII visibles (sin espacios). Uno inválido contesta 400 INVALID con el detalle en details.properties["Idempotency-Key"]. El header es opcional: sin él, el pedido se ejecuta como siempre.
Qué pasa en cada caso
| Situación | Respuesta |
|---|---|
| Primer pedido con esa key | Se ejecuta normalmente. |
| Reintento con la misma key y el mismo cuerpo, después de un éxito | La respuesta guardada del primero (mismo status y mismo cuerpo), con el header Idempotent-Replayed: true. No se ejecuta nada: no se crea ni se cobra nada de nuevo. |
| Reintento mientras el primero todavía corre | 409 IDEMPOTENCY_IN_FLIGHT. Espera unos segundos y reintenta. |
| La misma key con otro cuerpo o en otra ruta | 422 IDEMPOTENCY_KEY_REUSED. Una operación nueva necesita una key nueva. |
Reintento después de una negativa (4xx) o de un error nuestro (5xx) | Se ejecuta de nuevo. Solo se guardan los éxitos. |
Qué se guarda y cuánto dura
- Solo las respuestas exitosas (
2xxcon cuerpo JSON). Una negativa no hizo nada, así que no hay nada que proteger: el reintento vuelve a evaluarse con el estado de ese momento. Un error de nuestro lado libera la key, y el reintento corre de nuevo. - La respuesta se guarda 24 horas desde que el pedido terminó. Pasado ese plazo, la key queda libre y un pedido con ella se ejecuta como nuevo.
- Mientras el primer pedido corre, la key queda reservada como mucho 10 minutos. Si ese pedido se corta sin terminar (por ejemplo, porque superó el tiempo máximo de ejecución), a los 10 minutos la reserva vence y el siguiente reintento se ejecuta.
- Cada API key tiene sus propias keys de idempotencia. El mismo valor usado por dos integraciones con keys distintas son dos operaciones independientes; lo mismo entre dos personas.
- El cuerpo se compara byte por byte, junto con el método y la ruta. Un JSON con los mismos datos pero otro orden de campos u otros espacios es otro cuerpo y contesta
422. Serializa el cuerpo una vez y reusa ese string en cada intento.
Un reintento que devuelve la respuesta guardada sigue contando contra el límite de 60 pedidos por minuto.
Dónde se acepta
El header se lee en todas las acciones (POST /actions/<tool>) y en los POST de la API que crean algo o gastan. En cualquier otra ruta o método se ignora. En la especificación OpenAPI, esas operaciones declaran el parámetro Idempotency-Key.
Las tools del servidor MCP no usan este header: es solo de REST, y un cliente MCP que reintenta una tool la ejecuta de nuevo.
Recomendaciones
- Una key nueva por operación, la misma en todos sus reintentos. No reuses una key para «la misma clase» de operación: dos notas distintas son dos operaciones.
- Genera la key antes del primer intento y guárdala junto con el trabajo pendiente, para que un proceso que se reinicia pueda reintentar con la misma.
- Reintenta ante errores de red,
429,500,502,503y409 IDEMPOTENCY_IN_FLIGHT. Ante cualquier otro4xx, corrige el pedido: reintentarlo igual da la misma negativa. - Protocolos de varios pasos: si una acción se llama dos veces a propósito con el mismo cuerpo como parte de su flujo (por ejemplo,
upload_attachmentpara confirmar una subida), cada paso lleva su propia key; con la misma, el segundo paso devolvería la respuesta del primero.