Referência
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 UIcode— quando presente, é estável entre versões. Use para lógica programáticadetails— quando presente, contém diagnóstico estruturado (ex:details.fieldErrorsem 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 |
missing_permission | 403 | Conexão de agente: quem a autorizou não tem mais a permissão no CRM. Repetir não resolve |
creator_without_access | 403 | Conexão de agente: quem a autorizou não faz mais parte da organização |
forbidden | 403 | Recurso fora da organização da chave |
Validação
code | Status | Quando |
|---|---|---|
| (sem code) | 400 | Query inválida — veja details.fieldErrors |
invalid_idempotency_key | 400 | Idempotency-Key ausente ou fora do formato (escritas de tarefas e notas) |
invalid_json | 400 | Corpo que não é JSON (escritas de tarefas e notas) |
invalid_payload | 400 | Corpo inválido para o contrato (escritas de tarefas e notas) |
invalid_links | 400 | Negócio, contato ou conversa fora da organização (POST /tasks) |
invalid_assignee | 400 | Responsável não é membro aceito (POST /tasks) |
not_found | 404 | Tarefa, contato ou negócio fora da organização (escritas de tarefas e notas) |
idempotency_conflict | 409 | Idempotency-Key já usada com outro pedido |
invalid_state | 409 | Tarefa cancelada não pode ser concluída |
payload_too_large | 413 | Corpo acima de 64 KiB (escritas de tarefas e notas) |
daily_limit | 429 | Conexões de agente acima de 200 escritas em 24 horas; nada foi gravado |
Operacional
code | Status | Quando |
|---|---|---|
| (sem code) | 500 | Erro interno — reporte ao suporte com timestamp |
query_rejected | 500 | Leitura que o banco recusa sempre — não repita, reporte ao suporte |
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. A exceção é query_rejected, nos endpoints de leitura: a mesma chamada falha de novo, então não repita e reporte ao suporte.
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-1a8b2c3d4e5fReportar 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