Errores
El formato de los errores y cada código de error con su estado HTTP, qué significa y qué hacer al respecto — además de qué errores se pueden reintentar con seguridad.
Formato
Todo error — de la API o de los endpoints de la app — tiene la misma forma y nunca contiene un stack trace:
{
"error": {
"code": "INVALID_STATE",
"message": "Field company_size must be a number.",
"request_id": "req_7Gm2xPq9Lk4sVt1RbN8w"
}
}| Campo | Descripción |
|---|---|
code | Un código estable y legible por máquina, de las tablas de abajo. Decide según él — no según message. |
message | Una explicación legible para personas. Puede cambiar; no la analices. |
request_id | El ID de la solicitud, enviado también en el encabezado X-Request-ID. Inclúyelo cuando contactes con soporte. |
details | Datos extra opcionales, según el código (consulta details). |
Códigos de error
Solicitud y acceso
| Código | Estado | Significado | Qué hacer |
|---|---|---|---|
INVALID_REQUEST | 400 | La solicitud está mal formada: JSON inválido, un cuerpo que no es un objeto JSON, un Idempotency-Key o un parámetro de query inválido — como limit=1000 en GET /v1/executions. | Corrige la solicitud. details enumera los campos problemáticos cuando los hay. |
PAYLOAD_TOO_LARGE | 413 | El cuerpo de la solicitud supera los 128 KB (1 MB en POST /mcp, cuyas herramientas pueden llevar un decision schema; 32 MB en POST /v1/decisions/{slug} y POST /v1/hooks/{token}, cuyo estado puede llevar archivos). | Envía un cuerpo más pequeño — para un estado grande, envía solo los campos que necesitan las preguntas. Consulta Límites. |
INVALID_API_KEY | 401 | La clave de API falta, está mal formada, es desconocida o fue revocada. | Envía Authorization: Bearer <key> con una clave activa. |
UNAUTHORIZED | 401 | App: no has iniciado sesión, tu sesión expiró o se cerró — con Cerrar sesión en todas partes o un cambio de contraseña; también un e-mail o una contraseña incorrectos al iniciar sesión. URLs de webhook con un secreto: la llamada no tiene un Dcision-Signature ni un Authorization: Bearer whsec_… válidos. | Vuelve a iniciar sesión — o firma la llamada al webhook con el secreto actual. |
FORBIDDEN | 403 | No puedes hacer esto: una clave de API usada fuera de /v1; un workspace del que no eres miembro — entonces details.reason es "workspace_access"; o una acción que tu rol no permite — los Viewers no pueden cambiar nada; la configuración, las claves de proveedor, los secretos y los miembros requieren un Admin; la facturación, la propiedad y eliminar el workspace requieren al Owner. | Usa las claves de API solo en /v1. Para un rol, pídeselo a un Admin o al Owner — el mensaje indica el rol necesario. |
NOT_FOUND | 404 | App: la ejecución, la clave de API, la plantilla, el plan, la sesión de checkout, el miembro, la invitación, la entrega o el secreto no existe en este workspace. URLs de webhook: el token es desconocido, se rotó o el webhook está desactivado. | Revisa el ID — o vuelve a copiar la URL del webhook desde la pestaña Avanzado de la decisión. |
CONFLICT | 409 | El cambio entra en conflicto con el estado actual: un slug ya ocupado o bloqueado tras la primera publicación, un borrador guardado mientras tanto por otra persona, una publicación o creación concurrente, un límite (50 claves de API activas, 50 secretos, 50 invitaciones pendientes, 10 workspaces propios), una invitación para alguien que ya está en el workspace, un Owner que se va sin transferir la propiedad, la eliminación de un workspace con una suscripción de pago activa, una suscripción que ya existe o que no existe. | Recarga y luego sigue el mensaje. |
Decisiones
| Código | Estado | Significado | Qué hacer |
|---|---|---|---|
WORKSPACE_NOT_FOUND | 404 | Modo partner: el encabezado Dcision-Workspace o {ref} no corresponde a ningún sub-workspace del workspace de la clave de API. | Envía el id del sub-workspace o ext:<external_id> — consulta sub-workspaces. |
SLUG_TAKEN | 409 | Modo partner: mover una decisión a un sub-workspace que ya tiene una decisión con el mismo slug. details incluye decision_id, executions, deliveries y replaceable (la copia nunca se ejecutó). | Con replaceable: true, envía replace_empty: true para reemplazar la copia. Si no, primero renombra o elimina la decisión del sub-workspace. |
DECISION_NOT_FOUND | 404 | No hay ninguna decisión con este slug en el workspace de la clave de API, o el slug está mal formado. | Revisa el slug y que la clave pertenezca al workspace de la decisión. |
DECISION_NOT_DEPLOYED | 409 | La decisión existe, pero nunca se ha desplegado. | Despliégala desde su pestaña Publicar. |
DECISION_DISABLED | 409 | El endpoint de la decisión está desactivado. | Haz clic en Activar endpoint en su pestaña Publicar. |
INVALID_STATE | 422 | El estado no coincide con el schema del estado de la decisión, o es demasiado grande — por sí solo, o junto con las preguntas para el presupuesto de tokens del motor. message indica el campo o el límite. | Corrige el estado; para el presupuesto de tokens, envía solo los campos que necesitan las preguntas. No lo reintentes sin cambios. |
INVALID_SCHEMA | 422 | El decision schema es inválido — al guardar o desplegar un borrador. details enumera todos los problemas. | Corrige los problemas en el editor (Ir al error). |
IDEMPOTENCY_CONFLICT | 409 | El Idempotency-Key se usó en las últimas 24 horas con una solicitud diferente — o, con Retry-After: 1, la primera solicitud con esta clave sigue en ejecución. | Con Retry-After: espera y reintenta con la misma clave para obtener la respuesta almacenada. Sin él: usa una clave nueva para una solicitud nueva — consulta Idempotencia. |
Límites y facturación
| Código | Estado | Significado | Qué hacer |
|---|---|---|---|
RATE_LIMITED | 429 | Demasiadas solicitudes en el minuto actual para tu workspace — o los límites propios del Playground, o, en la app, demasiadas acciones de facturación (checkout, cambios de plan, portal…), invitaciones, códigos de inicio de sesión o intentos de inicio de sesión. | Espera Retry-After segundos y luego reintenta — consulta Límites de tasa. |
CREDITS_EXHAUSTED | 402 | Las decisiones incluidas en el plan para el período se agotaron y al workspace no le quedan créditos. | El Owner añade créditos o activa la recarga automática en la página Facturación (details.billingUrl), o mejora el plan. Reintentar antes de eso no sirve. |
SPEND_CAP_REACHED | 402 | Se alcanzó el tope de gasto del workspace para el ciclo de facturación. | El Owner sube o quita el tope en la página Facturación, o espera hasta details.periodEnd. |
QUOTA_EXCEEDED | 402 | Un plan configurado con tope estricto — o sin precio por 1M de decisiones — usó todas sus decisiones incluidas del período, así que no puede continuar con créditos. | Mejora el plan, o espera hasta details.periodEnd. Reintentar antes no sirve. |
PLAN_LIMIT_REACHED | 402 | El workspace ya tiene el número máximo de decisiones de su plan. | Elimina una decisión o mejora el plan. |
PAYMENT_FAILED | 402 | La tarjeta fue rechazada al cambiar de plan. | Actualiza el método de pago y vuelve a intentarlo. |
BILLING_NOT_CONFIGURED | 503 | Ese plan, intervalo o moneda aún no se puede comprar en línea. | Vuelve a intentarlo más tarde o escribe a sales@dcision.io. |
BILLING_PROVIDER_ERROR | 502 | El proveedor de pagos no pudo procesar la solicitud. | Vuelve a intentarlo en un momento. |
Motor
Dcision ya reintentó los fallos transitorios del motor — hasta 2 reintentos dentro del timeoutMs de la decisión — antes de devolver uno de estos errores. Una decisión con onEngineError: "fallback" responde en su lugar 200 con su acción de fallback, para todos los códigos de abajo excepto ENGINE_NOT_CONFIGURED — consulta Configuración de la decisión.
| Código | Estado | Significado | Qué hacer |
|---|---|---|---|
ENGINE_NOT_CONFIGURED | 424 | El workspace no tiene una credencial de motor utilizable: está seleccionada Mi propia clave del proveedor, pero no hay ninguna clave guardada para ese proveedor, o la clave del motor de Dcision no está disponible. | Añade la clave en Configuración → Motor, o cambia a la clave de Dcision. |
ENGINE_TIMEOUT | 504 | El motor no respondió dentro del timeoutMs de la decisión. | Reintenta con backoff y el mismo Idempotency-Key; sube timeoutMs si ocurre con frecuencia. |
ENGINE_RATE_LIMITED | 503 | El proveedor del motor está sobrecargado o con límite de tasa, o la clave de motor compartida de Dcision no tuvo un hueco libre antes del plazo. | Reintenta con backoff. Con tu propia clave, revisa los límites de tu proveedor. |
ENGINE_UNAVAILABLE | 503 | El proveedor del motor falló o no se pudo contactar. | Reintenta con backoff. |
ENGINE_INVALID_REQUEST | 502 | El proveedor rechazó la solicitud; el mensaje incluye su motivo. | Normalmente no es transitorio: revisa el estado y el modelo, luego contacta con soporte con el ID de la solicitud. |
ENGINE_AUTH_FAILED | 502 | El proveedor rechazó la clave del motor. | Corrige o reemplaza tu clave del proveedor en Configuración → Motor. |
ENGINE_ERROR | 502 | El motor respondió fuera del contrato de la decisión (una respuesta que falta o desconocida). | Reintenta una vez; si persiste, contacta con soporte con el ID de la solicitud. |
Servidor
| Código | Estado | Significado | Qué hacer |
|---|---|---|---|
INTERNAL_ERROR | 500 | Un error inesperado del lado de Dcision. | Reintenta con backoff; contacta con soporte con el ID de la solicitud si persiste. |
Reintentos
| Reintentar | No reintentar sin cambios |
|---|---|
429 RATE_LIMITED — tras Retry-After | 400, 401, 403, 404, 413, 422 |
409 IDEMPOTENCY_CONFLICT con Retry-After — misma clave, tras la espera | Cualquier otro 409 |
500 INTERNAL_ERROR | 402 CREDITS_EXHAUSTED, SPEND_CAP_REACHED, QUOTA_EXCEEDED, PLAN_LIMIT_REACHED, PAYMENT_FAILED |
503 ENGINE_RATE_LIMITED, ENGINE_UNAVAILABLE | 424 ENGINE_NOT_CONFIGURED |
504 ENGINE_TIMEOUT | 502 ENGINE_AUTH_FAILED, ENGINE_INVALID_REQUEST |
502 ENGINE_ERROR — una vez | |
| Errores de red y timeouts de tu lado |
Envía un Idempotency-Key para que un reintento tras una respuesta perdida no ejecute — ni cobre — la decisión dos veces. Hay un cliente completo en Reintentos idempotentes.
Los errores nunca se cobran, y tampoco los fallbacks por error del motor. Los estados inválidos y los fallos del motor se registran como ejecuciones con estado Error, para que puedas inspeccionarlos — en la app o con GET /v1/executions?status=error.
Detalles
details lleva datos estructurados para algunos códigos:
{
"error": {
"code": "INVALID_SCHEMA",
"message": "The decision schema is invalid.",
"request_id": "req_7Gm2xPq9Lk4sVt1RbN8w",
"details": [{ "path": "questions.0.options", "message": "Add at least 2 options (besides \"other\")." }]
}
}{
"error": {
"code": "CREDITS_EXHAUSTED",
"message": "The 2.5M decisions included in the Developer plan are used up and the workspace has no credits left. Add credits or turn on automatic recharge.",
"request_id": "req_Lz4Wq8nT1vXc7Rm2Kp9H",
"details": {
"used": 2500000,
"included": 2500000,
"availableCents": 0,
"currency": "usd",
"billingUrl": "https://app.dcision.io/billing"
}
}
}{
"error": {
"code": "SPEND_CAP_REACHED",
"message": "The workspace reached its spend cap of $50.00 for this billing cycle. Raise the cap or wait until 2026-11-01.",
"request_id": "req_Qm8Vr2Lx5Nc1Tw7Hk4Jd",
"details": {
"spendCapCents": 5000,
"spentCents": 5000,
"currency": "usd",
"periodEnd": "2026-11-01T00:00:00.000Z",
"billingUrl": "https://app.dcision.io/billing"
}
}
}{
"error": {
"code": "FORBIDDEN",
"message": "You don't have access to this workspace.",
"request_id": "req_Pw3Nx8Kd1Lq6Tz2Vb9Rc",
"details": { "reason": "workspace_access" }
}
}| Código | details |
|---|---|
INVALID_REQUEST | [{ "path", "message" }] para los campos inválidos, cuando están disponibles |
INVALID_SCHEMA | [{ "path", "message" }] — todos los problemas del schema |
CREDITS_EXHAUSTED | used, included, availableCents (el crédito restante, en centavos de currency — cero o ligeramente negativo), currency (usd o brl), billingUrl |
SPEND_CAP_REACHED | spendCapCents, spentCents (el gasto del ciclo con créditos, en centavos), currency, periodEnd (ISO 8601), billingUrl |
QUOTA_EXCEEDED | used, included, periodEnd (ISO 8601), upgradeUrl |
PLAN_LIMIT_REACHED | limit, used, upgradeUrl |
FORBIDDEN (acceso al workspace) | { "reason": "workspace_access" } — no eres (o ya no eres) miembro de ese workspace. Los rechazos por rol no llevan details. |
CONFLICT (borrador desactualizado) | currentRevision |
PAYMENT_FAILED | code, declineCode de la red de la tarjeta |
Eventos de webhook
El evento decision.completed del documento OpenAPI, con la solicitud enviada a los destinos webhook, sus headers, cada campo del evento y las respuestas que Dcision espera.
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.