Idempotencia
Reintenta de forma segura con el header Idempotency-Key — claves reservadas antes de la ejecución, reproducción de llamadas exitosas durante 24 horas, el header Idempotent-Replayed e IDEMPOTENCY_CONFLICT.
Un timeout o una conexión cortada pueden perder la respuesta de una decisión que sí se ejecutó. Reintentar a ciegas la ejecutaría — y la facturaría — dos veces. Envía un Idempotency-Key y un reintento recibirá en su lugar la respuesta guardada.
Idempotency-Key: lead-8421La clave tiene de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Cualquier otra cosa falla con 400 INVALID_REQUEST.
Comportamiento
| Situación | Qué pasa |
|---|---|
| Clave nueva | La clave se reserva para esta solicitud antes de que se ejecute la decisión. Si la decisión tiene éxito (200), su respuesta se guarda durante 24 horas. |
| Misma clave, misma solicitud, dentro de las 24 horas | Se devuelve la respuesta guardada con el header Idempotent-Replayed: true — el mismo execution_id, las mismas respuestas, las mismas entradas de destino. La decisión no se vuelve a ejecutar, no se factura nada, no se entrega nada y no se registra ninguna ejecución. |
| Misma clave, misma solicitud, mientras la primera todavía se ejecuta | 409 IDEMPOTENCY_CONFLICT con Retry-After: 1 — "A request with this Idempotency-Key is still running. Retry in a moment to get its response." Reintenta al cabo de un segundo: cuando la primera solicitud termine, recibirás su respuesta guardada. La decisión nunca se ejecuta dos veces. |
| Misma clave, solicitud distinta, dentro de las 24 horas | 409 IDEMPOTENCY_CONFLICT sin Retry-After — "This Idempotency-Key was already used with a different request body." — incluso mientras la primera solicitud se ejecuta. |
| Misma clave después de 24 horas | Se trata como una clave nueva. |
| La primera solicitud falló | La reserva se libera, así que un reintento con la misma clave vuelve a ejecutar la decisión. |
La primera solicitud recibió el fallback por error del motor (action_reason.type = "engine_error") | La reserva también se libera: un reintento con la misma clave vuelve a llegar al motor — y sus destinos se vuelven a disparar, con nuevos IDs de entrega. |
| La primera solicitud nunca terminó — el servidor se detuvo a mitad de la ejecución | La reserva vence después de 2 minutos; luego la clave puede volver a ejecutarse. |
"Misma solicitud" significa el mismo slug, el mismo state y el mismo valor de consulta include. El estado se compara después de parsear el JSON: los espacios en blanco no importan, pero el orden de las claves sí — {"a":1,"b":2} y {"b":2,"a":1} son solicitudes distintas. Construye el body de la misma forma en cada intento.
Elegir claves
Usa una clave por operación lógica y reutilízala en los reintentos de esa operación:
- el ID de aquello sobre lo que decides:
lead-8421,ticket:9f2c1d,msg_01HZX3…; - o un UUID generado una vez cuando empieza la operación — no uno por intento.
Las claves están limitadas a la clave de API que las envió: el mismo Idempotency-Key usado con una clave live y con una de test son dos claves distintas.
Ejemplo
# First call: runs the decision.
curl -i -X POST https://api.dcision.io/v1/decisions/spam-detection \
-H "Authorization: Bearer $DCISION_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: msg-20261005-0042" \
-d '{ "state": "Congratulations! You won a $1000 gift card, click here to claim now." }'
# Same call again: replayed.
# HTTP/1.1 200 OK
# Idempotent-Replayed: trueEnviar la misma llamada otra vez mientras la primera todavía se ejecuta devuelve 409 con Retry-After: 1; reintenta al cabo de un segundo para obtener su respuesta:
{
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "A request with this Idempotency-Key is still running. Retry in a moment to get its response.",
"request_id": "req_Hn5Wq2Lk8Tz1Vb4Xc7Pm"
}
}Enviar un estado distinto con msg-20261005-0042 dentro de las 24 horas devuelve:
{
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "This Idempotency-Key was already used with a different request body.",
"request_id": "req_Fw2Lk9Tq7Mz1Vb6Xc3Pn"
}
}Conviene saber
- Las reproducciones se sirven primero. Una reproducción se devuelve aunque la decisión se haya vuelto a desplegar o se haya desactivado después: recibes exactamente lo que devolvió la primera llamada, incluida su
version. - Las reproducciones cuentan para el rate limit, como cualquier solicitud autenticada.
- Los duplicados concurrentes son seguros. La clave se reserva antes de que se ejecute la decisión, así que dos solicitudes enviadas al mismo tiempo con la misma clave nunca se ejecutan ambas — ni se facturan ni entregan dos veces: la segunda recibe
409conRetry-After: 1, y su reintento recibe la respuesta guardada. Los SDKs esperan y reintentan por su cuenta. - Los errores liberan la clave. La clave se comprueba justo después de la autenticación, el rate limit y el body: cualquier fallo posterior — una decisión desconocida o desactivada, la cuota, un estado no válido, un error del motor — la libera, y el siguiente intento empieza de cero.
- Por subespacio. Con el header
Dcision-Workspace, el subespacio de destino forma parte de la solicitud: la misma clave usada para dos clientes es un conflicto409, nunca la respuesta guardada del otro cliente. - Las respuestas guardadas contienen las respuestas. Se conservan 24 horas sea cual sea la configuración
storeOutputde la decisión; el propio estado no se guarda para la idempotencia. - Los SDKs y la CLI lo hacen por ti. Los SDKs envían un
Idempotency-Keyen cada llamada adecidey lo reutilizan en sus reintentos;dcision decidegenera uno cuando no pasas ninguno y reintenta una vez ante errores de red — consulta CLI.
Consulta Reintentos idempotentes para un cliente completo en JavaScript y Python.
Límites de solicitudes
Límites de solicitudes por workspace en cada plan, ventanas separadas para decisiones y lecturas, los headers X-RateLimit en cada llamada, Retry-After en el 429 y cómo reducir el ritmo.
Límites
Todos los límites de tamaño y cantidad en un solo lugar — cuerpo de la solicitud, state y presupuesto de tokens, schema de decisión, destinos y entregas, identificadores, workspace, equipo e inicio de sesión.