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"
}
}| Campo | Descrição |
|---|---|
code | Um código estável, legível por máquina, das tabelas abaixo. Faça o switch nele — não em message. |
message | Uma explicação legível por pessoas. Pode mudar; não a interprete. |
request_id | O ID da requisição, também enviado no header X-Request-ID. Inclua-o ao falar com o suporte. |
details | Dados extras opcionais, conforme o código (veja details). |
Códigos de erro
Requisição e acesso
| Código | Status | Significado | O que fazer |
|---|---|---|---|
INVALID_REQUEST | 400 | A 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_LARGE | 413 | O 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_KEY | 401 | A API key está ausente, malformada, é desconhecida ou foi revogada. | Envie Authorization: Bearer <key> com uma chave ativa. |
UNAUTHORIZED | 401 | App: 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. |
FORBIDDEN | 403 | Você 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_FOUND | 404 | App: 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. |
CONFLICT | 409 | A 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ódigo | Status | Significado | O que fazer |
|---|---|---|---|
WORKSPACE_NOT_FOUND | 404 | Modo 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_TAKEN | 409 | Modo 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_FOUND | 404 | Nenhuma 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_DEPLOYED | 409 | A decisão existe, mas nunca foi publicada. | Publique-a na aba Publicar dela. |
DECISION_DISABLED | 409 | O endpoint da decisão está desativado. | Clique em Ativar endpoint na aba Publicar dela. |
INVALID_STATE | 422 | O 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_SCHEMA | 422 | O 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_CONFLICT | 409 | O 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ódigo | Status | Significado | O que fazer |
|---|---|---|---|
RATE_LIMITED | 429 | Requisiçõ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_EXHAUSTED | 402 | As 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_REACHED | 402 | O 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_EXCEEDED | 402 | Um 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_REACHED | 402 | O workspace já tem o número máximo de decisões do seu plano. | Exclua uma decisão ou faça upgrade. |
PAYMENT_FAILED | 402 | O cartão foi recusado ao mudar de plano. | Atualize a forma de pagamento e tente de novo. |
BILLING_NOT_CONFIGURED | 503 | Esse plano, intervalo ou moeda ainda não pode ser comprado online. | Tente de novo mais tarde ou escreva para sales@dcision.io. |
BILLING_PROVIDER_ERROR | 502 | O 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ódigo | Status | Significado | O que fazer |
|---|---|---|---|
ENGINE_NOT_CONFIGURED | 424 | O 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_TIMEOUT | 504 | O 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_LIMITED | 503 | O 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_UNAVAILABLE | 503 | O provedor do engine falhou ou não pôde ser alcançado. | Repita com backoff. |
ENGINE_INVALID_REQUEST | 502 | O 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_FAILED | 502 | O provedor rejeitou a chave do engine. | Corrija ou substitua a sua chave de provedor em Configurações → Engine. |
ENGINE_ERROR | 502 | O 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ódigo | Status | Significado | O que fazer |
|---|---|---|---|
INTERNAL_ERROR | 500 | Um erro inesperado do lado da Dcision. | Repita com backoff; fale com o suporte informando o request ID se persistir. |
Retries
| Repita | Não repita sem alterar |
|---|---|
429 RATE_LIMITED — depois de Retry-After | 400, 401, 403, 404, 413, 422 |
409 IDEMPOTENCY_CONFLICT com Retry-After — mesma chave, depois da espera | Qualquer outro 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 — 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:
{
"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 campos inválidos, quando disponível |
INVALID_SCHEMA | [{ "path", "message" }] — todos os problemas do schema |
CREDITS_EXHAUSTED | used, included, availableCents (o crédito restante, em centavos de currency — zero ou levemente negativo), currency (usd ou brl), billingUrl |
SPEND_CAP_REACHED | spendCapCents, spentCents (os gastos do ciclo com créditos, em centavos), currency, periodEnd (ISO 8601), billingUrl |
QUOTA_EXCEEDED | used, included, periodEnd (ISO 8601), upgradeUrl |
PLAN_LIMIT_REACHED | limit, 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_FAILED | code, declineCode da bandeira do cartão |
Eventos de webhook
O evento decision.completed do documento OpenAPI — a requisição enviada aos destinos de webhook, os headers, cada campo do evento e as respostas que a Dcision espera.
Rate limits
Limites de requisições por workspace em cada plano, janelas separadas para decisões e leituras, os headers X-RateLimit em toda chamada, Retry-After no 429 e como fazer backoff.