Reintentos idempotentes
Un cliente de Dcision listo para producción — claves de idempotencia, timeouts, qué errores reintentar, backoff exponencial con Retry-After — en JavaScript y Python.
Las redes fallan. Una solicitud puede agotar el tiempo de tu lado después de que la decisión se ejecutó, un proveedor puede estar sobrecargado por un momento, una ráfaga puede alcanzar tu límite de tasa. Un buen cliente reintenta los errores correctos, espera el tiempo correcto y nunca ejecuta — ni paga — la misma decisión dos veces.
Los SDKs oficiales hacen todo esto por ti. Esta guía muestra las reglas y un cliente completo para cuando llamas a la API directamente.
Las reglas
- Una
Idempotency-Keypor operación, reutilizada en cada reintento — el ID del lead, del ticket o del mensaje funciona bien. Así, un reintento de una llamada que tuvo éxito se reproduce durante 24 horas en lugar de ejecutarse de nuevo. - Construye el cuerpo siempre de la misma forma. La verificación de reproducción compara el state como JSON parseado, incluido el orden de las claves; un cuerpo distinto con la misma clave da
409 IDEMPOTENCY_CONFLICT. - Aplica el timeout de tu lado, un poco después que Dcision. Dcision ya reintenta el motor — hasta 2 reintentos — dentro del
timeoutMsde la decisión (5 segundos por defecto); 10 segundos de tu lado le dejan margen. Aumenta ambos a la vez. - Reintenta solo lo que puede tener éxito más tarde: errores de red,
429,500,503,504,409 IDEMPOTENCY_CONFLICTconRetry-After— la primera solicitud con esa clave sigue ejecutándose — y502 ENGINE_ERRORuna vez. Corrige todo lo demás. - Respeta
Retry-Afteren429y409; de lo contrario, aplica backoff exponencial con jitter. - Limita los intentos y luego sigue tu camino de error — normalmente el mismo que
escalate.
JavaScript
import { randomUUID } from "node:crypto";
const API = "https://api.dcision.io/v1/decisions";
const RETRYABLE_STATUS = new Set([429, 500, 503, 504]);
export class DcisionError extends Error {
constructor(status, error) {
super(`${error.code}: ${error.message}`);
Object.assign(this, { status, code: error.code, requestId: error.request_id, details: error.details });
}
}
/** Runs a decision with retries. Pass a stable idempotencyKey (e.g. the record's ID) per operation. */
export async function decide(slug, state, { idempotencyKey = randomUUID(), attempts = 4, timeoutMs = 10_000 } = {}) {
for (let attempt = 1; ; attempt++) {
let response;
try {
response = await fetch(`${API}/${slug}`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DCISION_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({ state }),
signal: AbortSignal.timeout(timeoutMs),
});
} catch (networkError) {
// The decision may or may not have run: the same Idempotency-Key makes the retry safe.
if (attempt >= attempts) throw networkError;
await sleep(backoff(attempt));
continue;
}
const body = await readJson(response);
if (response.ok) return body;
const error = body?.error ?? { code: "INTERNAL_ERROR", message: `HTTP ${response.status}` };
const retryable =
RETRYABLE_STATUS.has(response.status) ||
(error.code === "ENGINE_ERROR" && attempt === 1) ||
// Same key still running: wait for Retry-After, then get its stored response.
(error.code === "IDEMPOTENCY_CONFLICT" && response.headers.has("Retry-After"));
if (!retryable || attempt >= attempts) throw new DcisionError(response.status, error);
const retryAfter = Number(response.headers.get("Retry-After"));
await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
}
}
async function readJson(response) {
try {
return await response.json();
} catch {
return null; // e.g. an HTML error page from a proxy
}
}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const backoff = (attempt) => Math.min(8_000, 250 * 2 ** attempt) * (0.5 + Math.random() / 2);import { DcisionError, decide } from "./dcision.js";
try {
const decision = await decide("lead-qualification", { message: lead.message, company_size: lead.size }, {
idempotencyKey: `lead-${lead.id}`,
});
await act(decision);
} catch (error) {
if (error instanceof DcisionError && error.code === "INVALID_STATE") return reportBadInput(lead, error.message);
await escalate(lead, error); // retries exhausted or a non-retryable error
}Python
import os
import random
import time
import uuid
import requests
API = "https://api.dcision.io/v1/decisions"
RETRYABLE_STATUS = {429, 500, 503, 504}
class DcisionError(Exception):
def __init__(self, status, error):
super().__init__(f"{error['code']}: {error['message']}")
self.status = status
self.code = error["code"]
self.request_id = error.get("request_id")
self.details = error.get("details")
def decide(slug, state, idempotency_key=None, attempts=4, timeout=10):
"""Runs a decision with retries. Pass a stable idempotency_key (e.g. the record's ID) per operation."""
key = idempotency_key or str(uuid.uuid4())
for attempt in range(1, attempts + 1):
try:
response = requests.post(
f"{API}/{slug}",
headers={
"Authorization": f"Bearer {os.environ['DCISION_API_KEY']}",
"Idempotency-Key": key,
},
json={"state": state},
timeout=timeout,
)
except requests.RequestException:
# The decision may or may not have run: the same Idempotency-Key makes the retry safe.
if attempt == attempts:
raise
time.sleep(_backoff(attempt))
continue
try:
body = response.json()
except ValueError:
body = None # e.g. an HTML error page from a proxy
if response.ok:
return body
error = (body or {}).get("error") or {"code": "INTERNAL_ERROR", "message": f"HTTP {response.status_code}"}
retryable = (
response.status_code in RETRYABLE_STATUS
or (error["code"] == "ENGINE_ERROR" and attempt == 1)
# Same key still running: wait for Retry-After, then get its stored response.
or (error["code"] == "IDEMPOTENCY_CONFLICT" and "Retry-After" in response.headers)
)
if not retryable or attempt == attempts:
raise DcisionError(response.status_code, error)
retry_after = response.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else _backoff(attempt))
def _backoff(attempt):
return min(8.0, 0.25 * 2**attempt) * (0.5 + random.random() / 2)from dcision import DcisionError, decide
try:
decision = decide(
"support-routing",
{"message": ticket["message"], "plan": ticket["plan"]},
idempotency_key=f"ticket-{ticket['id']}",
)
act(decision)
except DcisionError as error:
escalate(ticket, error)Qué no hacer
- No generes una nueva
Idempotency-Keypor intento — los reintentos se ejecutarían, y se facturarían, otra vez. - No compitas con tus propios reintentos. Dos solicitudes enviadas al mismo tiempo con la misma clave nunca se ejecutan ambas — la segunda recibe
409conRetry-After: 1— pero cuesta un viaje de ida y vuelta y un lugar en el límite de tasa. Reintenta después de un fallo o de un timeout. - No reintentes errores
4xxsin cambios (salvo429):INVALID_STATE,DECISION_DISABLED,CREDITS_EXHAUSTEDoQUOTA_EXCEEDEDno se arreglan solos. - No trates
IDEMPOTENCY_CONFLICTsinRetry-Aftercomo transitorio. Significa que dos solicitudes distintas comparten una clave — un bug en cómo se construyen las claves. ConRetry-After, solo significa que la primera solicitud sigue ejecutándose.
Con el fallback por error del motor
Una decisión cuyo onEngineError es fallback responde 200 incluso cuando el motor falla, con action_reason.type = "engine_error". El cliente de arriba la devuelve como cualquier otra respuesta. Si prefieres tener respuestas reales cuando esperarlas es barato, reinténtala más tarde con la misma clave: las respuestas de fallback no se facturan ni se guardan para idempotencia, así que el reintento vuelve a llegar al motor — y vuelve a disparar los destinos de la decisión, con nuevos IDs de entrega.
const decision = await decide("lead-qualification", state, { idempotencyKey: `lead-${lead.id}` });
if (decision.action_reason.type === "engine_error") queue.retryLater({ lead, idempotencyKey: `lead-${lead.id}` });El dcision decide del CLI sigue las mismas reglas: genera una Idempotency-Key cuando no pasas una y reintenta una vez ante errores de red.
Resumen y calibración
Lee la pestaña Resumen de una decisión — ejecuciones, tasa de éxito, latencia, costo, acciones, motivos y estadísticas por pregunta — y actúa sobre cada sugerencia de calibración, con sus umbrales.
Planes, cuotas y facturación
Genesis, Developer, Growth y Enterprise — decisiones incluidas, créditos prepagos, rate limits, límites de decisiones y logs — qué se cobra y cómo funcionan créditos, mejoras, bajadas, cancelaciones y facturas.