Tratamento de Erros

Todas as APIs da plataforma retornam erros em um formato JSON consistente. Entenda o contrato de erros antes de começar a integrar.

Formato da Resposta de Erro

Estrutura padrão

{
  "error": "descrição do erro em inglês",
  "code": 400
}

Campo	Tipo	Descrição
error	string	Mensagem descritiva do erro
code	integer	Código HTTP do erro (espelha o status da resposta)

Códigos de Status HTTP

Status	Nome	Quando ocorre
400	Bad Request	Parâmetros inválidos, campos obrigatórios ausentes ou formato incorreto
401	Unauthorized	Token ausente, inválido ou expirado
403	Forbidden	Token válido, mas sem permissão para o recurso (fora do escopo)
404	Not Found	Recurso não encontrado (ID inexistente ou removido)
409	Conflict	Conflito com estado existente (ex.: CNPJ já cadastrado)
422	Unprocessable Entity	Dados bem formados mas semanticamente inválidos
500	Internal Server Error	Erro interno na plataforma — contate o suporte