Erros

Toda resposta de erro tem o mesmo formato, com status HTTP coerente e um código estável.

Formato

{
  "error": {
    "code": "INVALID_WINDOW",
    "message": "janela invertida: since 2026-09-30 é depois de until 2026-09-01",
    "trace_id": "1700000000000000000"
  }
}

Campo	Uso
code	Código estável. É seguro comparar no seu código.
message	Texto para pessoas. Pode mudar entre versões; não decida nada a partir dele.
trace_id	Identificador da ocorrência. Registre-o no seu log e cite-o ao pedir suporte.

Sempre decida pelo status HTTP e por error.code. Nunca por error.message.

Códigos

Status	code	Significado	Tratamento
400	INVALID_WINDOW	Data fora do formato, inexistente, fora da faixa, janela invertida ou maior que o máximo.	Corrija a requisição. Não repita igual.
400	INVALID_LIMIT	limit fora de 1 a 1000.	Corrija a requisição.
401	SEM_CHAVE	Troca de token sem Authorization.	Envie a chave no cabeçalho.
401	CHAVE_INVALIDA	Chave inexistente, malformada, vencida ou revogada.	Não repita. Confira ou peça outra chave.
401	NO_TOKEN	Leitura sem token.	Envie o token.
401	INVALID_TOKEN	Token vencido, malformado ou com assinatura inválida.	Troque a chave por novo token e repita uma vez.
403	TENANT_MISMATCH	O cliente do caminho não é o do token.	Use o tenant_id da troca. Não repita igual.
403	FORBIDDEN	O papel não inclui a permissão da rota.	Não repita. Veja Permissões e escopo.
404	(varia)	Rota inexistente, ou recurso de outro cliente nas rotas de detalhe de público.	Confira o caminho e o identificador.
500	QUERY_FAILED, INTERNAL	Falha do nosso lado ao montar a resposta.	Repita com espera crescente. Se persistir, cite o trace_id no suporte.

Algumas rotas podem devolver outros códigos específicos, descritos na Referência. A regra geral vale para todos: 4xx é problema da requisição e não melhora se repetida; 5xx pode ser transitório.

Como tratar

1. Falhas de rede e 5xx. Repita com backoff exponencial e variação aleatória, com um número máximo de tentativas. Veja Limites de uso e boas maneiras.
2. 401 com INVALID_TOKEN. O token venceu. Troque a chave por um novo e repita a leitura uma única vez. Se o 401 voltar, a chave perdeu a validade: pare e avise quem cuida da integração.
3. 401 com CHAVE_INVALIDA. Não tente de novo em laço. Uma chave vencida só volta a funcionar com uma nova.
4. 403. É um erro de configuração, não transitório. Falhe de forma visível.
5. 400. É erro de programação ou de dado de entrada. Registre a requisição (sem o token) e corrija.
6. Resposta 200 com listas vazias. Não é erro. Antes de concluir que não há dados, confira a janela e o estado das contas. Veja Unidades e tipos.

Registrar sem vazar

No log, grave o status, error.code, trace_id, o método e o caminho. Não grave o cabeçalho Authorization, a chave nem o token.

Próximos passos

• Limites de uso e boas maneiras
• Autenticação
• Início rápido