Erros

Formato

Erros de regra de negócio e de validação vêm com a mensagem em message:

{ "message": "Já existe um colaborador associado ao email ana@suaempresa.com.br" }

Erros de autenticação e autorização vêm em error, porque são recusados antes de a requisição chegar à rota:

{ "error": "Expired JWT token" }

As mensagens são escritas para pessoas, em português, e podem mudar de redação. Decida pelo status HTTP, não pelo texto.

Status

Status	Quando acontece
400	Corpo malformado, campo obrigatório ausente, parâmetro com tipo errado, regra de negócio violada
401	Token ausente (JWT token required), vencido (Expired JWT token) ou credencial inválida
403	Token inválido, ou o usuário não tem papel, módulo ou permissão — veja permissões
404	Registro inexistente (ou de outra conta) e rota inexistente
405	Método HTTP não aceito na rota
409	Registro duplicado, exclusão bloqueada por dependências, campo obrigatório do banco não informado, e-mail com conta em mais de uma empresa no login
410	Recurso que existiu e não está mais disponível (link vencido, dispositivo revogado)
415	Content-Type não suportado
423	Recurso bloqueado (por exemplo, PIN bloqueado por tentativas)
429	Limite de requisições excedido — veja limites
500	Erro inesperado

Erro inesperado

Um 500 traz um código de referência:

{ "message": "Erro interno. Referência: 7f3a9c1e" }

Ao falar com o suporte, informe esse código, a rota e o horário — ele localiza o registro exato do erro.

Validação de campos

Quando a rota valida o corpo, a resposta 400 lista cada campo recusado e o motivo:

Erro de validação: <campo>: <motivo>, <campo>: <motivo>

Parâmetros e cabeçalhos ausentes também saem nomeados — Parâmetro obrigatório ausente: page, Header obrigatório ausente: X-Dispositivo-Token.

Tentar de novo?

Status	Repetir?
401 com Expired JWT token	Sim, depois de renovar o token
429	Sim, depois de esperar — os limites são por minuto
500, 502, 503, 504	Sim, com espera crescente, e só para operações idempotentes (GET, PUT, DELETE)
400, 403, 404, 409	Não — a mesma chamada vai dar o mesmo resultado