Códigos de erro

Formato de erro flat, códigos HTTP, códigos `code` estáveis e estratégia de retry.

Formato

{
  "error": "string — mensagem humana legível",
  "code": "string_estavel — opcional, para máquinas",
  "details": {}
}

error — sempre presente. Use para logs e mensagens de UI
code — quando presente, é estável entre versões. Use para lógica programática
details — quando presente, contém diagnóstico estruturado (ex: details.fieldErrors em 400)

Importante: o formato é flat, não nested. Não há error.message ou error.code — é body.error e body.code direto na raiz.

Códigos HTTP

Status	Significado	Retry?
200	Sucesso	—
400	Parâmetros malformados ou faltando	❌
401	Autenticação ausente, inválida ou revogada	❌
403	Autenticação válida mas sem permissão	❌
404	Recurso não encontrado	❌
409	Conflito (race condition em escrita)	✅ (com idempotency)
422	Validação semântica falhou	❌
429	Rate limit excedido	✅ (respeitar `Retry-After`)
500	Erro interno	✅
502	Gateway error (upstream)	✅
503	Indisponível (manutenção ou degradação)	✅
504	Gateway timeout	✅

Códigos `code` estáveis

Autenticação

`code`	Status	Quando
`missing_api_key`	401	Header `Authorization` ausente
`invalid_api_key`	401	Chave malformada ou nunca existiu
`revoked_api_key`	401	Chave revogada
`expired_api_key`	401	Chave passou da data de expiração
`missing_scope`	403	Chave válida mas falta escopo
`forbidden`	403	Recurso fora da organização da chave

Validação

`code`	Status	Quando
(sem code)	400	Query inválida — veja `details.fieldErrors`

Operacional

`code`	Status	Quando
(sem code)	500	Erro interno — reporte ao suporte com timestamp

Exemplos

400 — query inválida

{
  "error": "Invalid query",
  "details": {
    "fieldErrors": {
      "organization_id": ["organization_id must be uuid"]
    },
    "formErrors": []
  }
}

401 — chave revogada

{
  "error": "API key was revoked",
  "code": "revoked_api_key"
}

403 — escopo faltando

{
  "error": "Required scope missing: messages:read",
  "code": "missing_scope"
}

500 — erro interno

{
  "error": "Internal server error"
}

Sem code em 500 é intencional — você não deve ramificar lógica em "tipo de erro interno", apenas retry com backoff e reportar ao suporte se persistir.

Retry strategy

Veja Erros e retry para o algoritmo completo de backoff exponencial com jitter.

Idempotência

Para POST/PUT/DELETE futuros, use header Idempotency-Key (UUID v4 por intenção de negócio). Resultado cacheado por 24h.

Idempotency-Key: 5a2c7e8f-d4b1-4c3a-9f5e-1a8b2c3d4e5f

Reportar ao suporte

Para erros 500 recorrentes, abra ticket em Suporte incluindo:

Endpoint chamado
Timestamp (ISO 8601 com timezone)
Resposta completa do servidor
ID da API key (apenas o prefixo, nunca a chave inteira)
Request ID se exposto em header X-Request-Id

On this page