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

La clave tiene de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Cualquier otra cosa falla con 400 INVALID_REQUEST.

Comportamiento

SituaciónQué pasa
Clave nuevaLa 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 horasSe 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 ejecuta409 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 horas409 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 horasSe 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ónLa 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: true

Enviar 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:

409 Conflict — todavía en ejecución
{
  "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:

409 Conflict
{
  "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 409 con Retry-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 conflicto 409, nunca la respuesta guardada del otro cliente.
  • Las respuestas guardadas contienen las respuestas. Se conservan 24 horas sea cual sea la configuración storeOutput de 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-Key en cada llamada a decide y lo reutilizan en sus reintentos; dcision decide genera 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.

En esta página