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"
  }
}
CampoDescripción
codeUn código estable y legible por máquina, de las tablas de abajo. Decide según él — no según message.
messageUna explicación legible para personas. Puede cambiar; no la analices.
request_idEl ID de la solicitud, enviado también en el encabezado X-Request-ID. Inclúyelo cuando contactes con soporte.
detailsDatos extra opcionales, según el código (consulta details).

Códigos de error

Solicitud y acceso

CódigoEstadoSignificadoQué hacer
INVALID_REQUEST400La 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_LARGE413El 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_KEY401La clave de API falta, está mal formada, es desconocida o fue revocada.Envía Authorization: Bearer <key> con una clave activa.
UNAUTHORIZED401App: 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.
FORBIDDEN403No 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_FOUND404App: 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.
CONFLICT409El 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ódigoEstadoSignificadoQué hacer
WORKSPACE_NOT_FOUND404Modo 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_TAKEN409Modo 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_FOUND404No 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_DEPLOYED409La decisión existe, pero nunca se ha desplegado.Despliégala desde su pestaña Publicar.
DECISION_DISABLED409El endpoint de la decisión está desactivado.Haz clic en Activar endpoint en su pestaña Publicar.
INVALID_STATE422El 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_SCHEMA422El 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_CONFLICT409El 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ódigoEstadoSignificadoQué hacer
RATE_LIMITED429Demasiadas 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_EXHAUSTED402Las 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_REACHED402Se 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_EXCEEDED402Un 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_REACHED402El workspace ya tiene el número máximo de decisiones de su plan.Elimina una decisión o mejora el plan.
PAYMENT_FAILED402La tarjeta fue rechazada al cambiar de plan.Actualiza el método de pago y vuelve a intentarlo.
BILLING_NOT_CONFIGURED503Ese 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_ERROR502El 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ódigoEstadoSignificadoQué hacer
ENGINE_NOT_CONFIGURED424El 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_TIMEOUT504El 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_LIMITED503El 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_UNAVAILABLE503El proveedor del motor falló o no se pudo contactar.Reintenta con backoff.
ENGINE_INVALID_REQUEST502El 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_FAILED502El proveedor rechazó la clave del motor.Corrige o reemplaza tu clave del proveedor en Configuración → Motor.
ENGINE_ERROR502El 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ódigoEstadoSignificadoQué hacer
INTERNAL_ERROR500Un error inesperado del lado de Dcision.Reintenta con backoff; contacta con soporte con el ID de la solicitud si persiste.

Reintentos

ReintentarNo reintentar sin cambios
429 RATE_LIMITED — tras Retry-After400, 401, 403, 404, 413, 422
409 IDEMPOTENCY_CONFLICT con Retry-After — misma clave, tras la esperaCualquier otro 409
500 INTERNAL_ERROR402 CREDITS_EXHAUSTED, SPEND_CAP_REACHED, QUOTA_EXCEEDED, PLAN_LIMIT_REACHED, PAYMENT_FAILED
503 ENGINE_RATE_LIMITED, ENGINE_UNAVAILABLE424 ENGINE_NOT_CONFIGURED
504 ENGINE_TIMEOUT502 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:

422 INVALID_SCHEMA
{
  "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\")." }]
  }
}
402 CREDITS_EXHAUSTED
{
  "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"
    }
  }
}
402 SPEND_CAP_REACHED
{
  "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"
    }
  }
}
403 FORBIDDEN — no eres miembro del workspace
{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have access to this workspace.",
    "request_id": "req_Pw3Nx8Kd1Lq6Tz2Vb9Rc",
    "details": { "reason": "workspace_access" }
  }
}
Códigodetails
INVALID_REQUEST[{ "path", "message" }] para los campos inválidos, cuando están disponibles
INVALID_SCHEMA[{ "path", "message" }] — todos los problemas del schema
CREDITS_EXHAUSTEDused, included, availableCents (el crédito restante, en centavos de currency — cero o ligeramente negativo), currency (usd o brl), billingUrl
SPEND_CAP_REACHEDspendCapCents, spentCents (el gasto del ciclo con créditos, en centavos), currency, periodEnd (ISO 8601), billingUrl
QUOTA_EXCEEDEDused, included, periodEnd (ISO 8601), upgradeUrl
PLAN_LIMIT_REACHEDlimit, 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_FAILEDcode, declineCode de la red de la tarjeta

En esta página