Erros

O formato de erro e todos os códigos de erro com o status HTTP, o que significam e o que fazer — além de quais erros podem ser repetidos com segurança.

Formato

Todo erro — da API ou dos endpoints do app — tem o mesmo formato e nunca contém um stack trace:

{
  "error": {
    "code": "INVALID_STATE",
    "message": "Field company_size must be a number.",
    "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w"
  }
}
CampoDescrição
codeUm código estável, legível por máquina, das tabelas abaixo. Faça o switch nele — não em message.
messageUma explicação legível por pessoas. Pode mudar; não a interprete.
request_idO ID da requisição, também enviado no header X-Request-ID. Inclua-o ao falar com o suporte.
detailsDados extras opcionais, conforme o código (veja details).

Códigos de erro

Requisição e acesso

CódigoStatusSignificadoO que fazer
INVALID_REQUEST400A requisição está malformada: JSON inválido, um corpo que não é um objeto JSON, um Idempotency-Key ou parâmetro de query inválido — como limit=1000 em GET /v1/executions.Corrija a requisição. details lista os campos problemáticos, quando houver.
PAYLOAD_TOO_LARGE413O corpo da requisição passa de 128 KB (1 MB em POST /mcp, cujas ferramentas podem levar um decision schema; 32 MB em POST /v1/decisions/{slug} e POST /v1/hooks/{token}, cujo estado pode levar arquivos).Envie um corpo menor — para um estado grande, envie só os campos de que as perguntas precisam. Veja Limites.
INVALID_API_KEY401A API key está ausente, malformada, é desconhecida ou foi revogada.Envie Authorization: Bearer <key> com uma chave ativa.
UNAUTHORIZED401App: você não está logado, a sua sessão expirou ou foi encerrada — por Sair de todos os dispositivos ou por uma troca de senha; também um e-mail ou senha incorretos no login. URLs de webhook com segredo: a chamada não tem um Dcision-Signature ou Authorization: Bearer whsec_… válido.Entre de novo — ou assine a chamada do webhook com o segredo atual.
FORBIDDEN403Você não pode fazer isso: uma API key usada fora de /v1; um workspace do qual você não é membro — então details.reason é "workspace_access"; ou uma ação que o seu papel não permite — Leitores não podem alterar nada; configurações, chaves de provedor, segredos e membros exigem um Admin; cobrança, propriedade e exclusão do workspace exigem o Proprietário.Use API keys só em /v1. Para um papel, peça a um Admin ou ao Proprietário — a mensagem informa o papel necessário.
NOT_FOUND404App: a execução, API key, template, plano, sessão de checkout, membro, convite, entrega ou segredo não existe neste workspace. URLs de webhook: o token é desconhecido, foi rotacionado, ou o webhook está desligado.Verifique o ID — ou copie a URL do webhook de novo na aba Avançado da decisão.
CONFLICT409A alteração conflita com o estado atual: um slug já em uso ou travado depois do primeiro deploy, um rascunho salvo enquanto isso por outra pessoa, um deploy ou criação simultâneos, um limite (50 API keys ativas, 50 segredos, 50 convites pendentes, 10 workspaces próprios), um convite para alguém que já está no workspace, um Proprietário saindo sem transferir, a exclusão de um workspace com uma assinatura paga ativa, uma assinatura que já existe ou que não existe.Recarregue e siga a mensagem.

Decisões

CódigoStatusSignificadoO que fazer
WORKSPACE_NOT_FOUND404Modo parceiro: o header Dcision-Workspace ou {ref} não aponta para nenhum sub-workspace do workspace da API key.Envie o id do sub-workspace ou ext:<external_id> — veja sub-workspaces.
SLUG_TAKEN409Modo parceiro: mover uma decisão para um sub-workspace que já tem uma decisão com o mesmo slug. details traz decision_id, executions, deliveries e replaceable (a cópia nunca rodou).Com replaceable: true, envie replace_empty: true para substituir a cópia. Caso contrário, renomeie ou exclua antes a decisão do sub-workspace.
DECISION_NOT_FOUND404Nenhuma decisão com este slug no workspace da API key, ou um slug malformado.Verifique o slug e se a chave pertence ao workspace da decisão.
DECISION_NOT_DEPLOYED409A decisão existe, mas nunca foi publicada.Publique-a na aba Publicar dela.
DECISION_DISABLED409O endpoint da decisão está desativado.Clique em Ativar endpoint na aba Publicar dela.
INVALID_STATE422O estado não bate com o state schema da decisão, ou é grande demais — sozinho, ou junto com as perguntas para o orçamento de tokens do engine. message informa o campo ou o limite.Corrija o estado; para o orçamento de tokens, envie só os campos de que as perguntas precisam. Não repita sem alterar.
INVALID_SCHEMA422O decision schema é inválido — ao salvar ou publicar um rascunho. details lista todos os problemas.Corrija os problemas no editor (Ir para o erro).
IDEMPOTENCY_CONFLICT409O Idempotency-Key foi usado nas últimas 24 horas com uma requisição diferente — ou, com Retry-After: 1, a primeira requisição com essa chave ainda está rodando.Com Retry-After: espere e repita com a mesma chave para receber a resposta armazenada. Sem ele: use uma chave nova para uma requisição nova — veja Idempotência.

Limites e cobrança

CódigoStatusSignificadoO que fazer
RATE_LIMITED429Requisições demais no minuto atual para o seu workspace — ou os limites próprios do Playground, ou, no app, ações de cobrança demais (checkout, mudanças de plano, portal…), convites, códigos de login ou tentativas de login.Espere Retry-After segundos e repita — veja Rate limits.
CREDITS_EXHAUSTED402As decisões incluídas no plano para o período acabaram e o workspace não tem mais créditos.O Proprietário adiciona créditos ou ativa a recarga automática na página Cobrança (details.billingUrl), ou faz upgrade. Repetir antes disso não adianta.
SPEND_CAP_REACHED402O limite de gastos do workspace para o ciclo de cobrança foi atingido.O Proprietário aumenta ou remove o limite na página Cobrança, ou espere até details.periodEnd.
QUOTA_EXCEEDED402Um plano configurado com limite rígido — ou sem preço por 1M de decisões — usou todas as decisões incluídas no período, então não pode continuar com créditos.Faça upgrade, ou espere até details.periodEnd. Repetir antes não adianta.
PLAN_LIMIT_REACHED402O workspace já tem o número máximo de decisões do seu plano.Exclua uma decisão ou faça upgrade.
PAYMENT_FAILED402O cartão foi recusado ao mudar de plano.Atualize a forma de pagamento e tente de novo.
BILLING_NOT_CONFIGURED503Esse plano, intervalo ou moeda ainda não pode ser comprado online.Tente de novo mais tarde ou escreva para sales@dcision.io.
BILLING_PROVIDER_ERROR502O provedor de pagamento não conseguiu processar a requisição.Tente de novo daqui a pouco.

Engine

A Dcision já repetiu falhas transitórias do engine — até 2 retries dentro do timeoutMs da decisão — antes de devolver um destes erros. Uma decisão com onEngineError: "fallback" responde 200 com a sua ação de fallback, para todos os códigos abaixo exceto ENGINE_NOT_CONFIGURED — veja Configurações da decisão.

CódigoStatusSignificadoO que fazer
ENGINE_NOT_CONFIGURED424O workspace não tem uma credencial de engine utilizável: Minha própria chave de provedor está selecionada, mas nenhuma chave foi salva para esse provedor, ou a chave de engine da Dcision está indisponível.Adicione a chave em Configurações → Engine, ou mude para a chave da Dcision.
ENGINE_TIMEOUT504O engine não respondeu dentro do timeoutMs da decisão.Repita com backoff e o mesmo Idempotency-Key; aumente timeoutMs se acontecer com frequência.
ENGINE_RATE_LIMITED503O provedor do engine está sobrecarregado ou com rate limit, ou a chave de engine compartilhada da Dcision não teve vaga livre antes do prazo.Repita com backoff. Com a sua própria chave, verifique os limites do seu provedor.
ENGINE_UNAVAILABLE503O provedor do engine falhou ou não pôde ser alcançado.Repita com backoff.
ENGINE_INVALID_REQUEST502O provedor rejeitou a requisição; a mensagem inclui o motivo.Normalmente não é transitório: verifique o estado e o modelo, depois fale com o suporte informando o request ID.
ENGINE_AUTH_FAILED502O provedor rejeitou a chave do engine.Corrija ou substitua a sua chave de provedor em Configurações → Engine.
ENGINE_ERROR502O engine respondeu fora do contrato da decisão (uma resposta ausente ou desconhecida).Repita uma vez; se persistir, fale com o suporte informando o request ID.

Servidor

CódigoStatusSignificadoO que fazer
INTERNAL_ERROR500Um erro inesperado do lado da Dcision.Repita com backoff; fale com o suporte informando o request ID se persistir.

Retries

RepitaNão repita sem alterar
429 RATE_LIMITED — depois de Retry-After400, 401, 403, 404, 413, 422
409 IDEMPOTENCY_CONFLICT com Retry-After — mesma chave, depois da esperaQualquer outro 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 — uma vez
Erros de rede e timeouts do seu lado

Envie um Idempotency-Key para que um retry depois de uma resposta perdida não execute — nem cobre — a decisão duas vezes. Um cliente completo está em Retries idempotentes.

Erros nunca são cobrados, nem fallbacks por erro do engine. Estados inválidos e falhas do engine são registrados como execuções com status Erro, para que você possa inspecioná-los — no app ou com GET /v1/executions?status=error.

Details

details traz dados estruturados para alguns 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 — não é membro do 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 campos inválidos, quando disponível
INVALID_SCHEMA[{ "path", "message" }] — todos os problemas do schema
CREDITS_EXHAUSTEDused, included, availableCents (o crédito restante, em centavos de currency — zero ou levemente negativo), currency (usd ou brl), billingUrl
SPEND_CAP_REACHEDspendCapCents, spentCents (os gastos do ciclo com créditos, em centavos), currency, periodEnd (ISO 8601), billingUrl
QUOTA_EXCEEDEDused, included, periodEnd (ISO 8601), upgradeUrl
PLAN_LIMIT_REACHEDlimit, used, upgradeUrl
FORBIDDEN (acesso ao workspace){ "reason": "workspace_access" } — você não é (mais) membro desse workspace. Recusas por papel não trazem details.
CONFLICT (rascunho desatualizado)currentRevision
PAYMENT_FAILEDcode, declineCode da bandeira do cartão

Nesta página