Erros

A Merx API utiliza códigos HTTP padrão para indicar sucesso ou falha. Códigos 2xx indicam sucesso, 4xx indicam erros de cliente, 5xx indicam erros de servidor.

Formato de Erros

A maioria dos erros retorna um objeto JSON com um array de mensagens:

{
  "messages": ["descrição do erro"]
}

Códigos de Erro Comuns

400 — Bad Request

Validação de campo falhou:

{
  "messages": ["message.producer.social-identity.invalid"]
}

401 — Unauthorized

Retornado pelo Kong gateway quando a Authorization está ausente ou inválida. Sem body de resposta (resposta direta do gateway).

403 — Forbidden

Mensagem de texto simples (sem wrapper JSON)

Ocorre quando a Authorization não tem permissão de acesso ao recurso solicitado.

404 — Not Found

{
  "messages": ["message.entidade.not-found"]
}

Nota: Alguns endpoints de listagem retornam 404 quando nenhum registro existe, ao invés de um array vazio. Exemplo: GET /producers retorna {"messages": ["message.producer.not-found"]} se nenhum produtor estiver cadastrado.

502 — Bad Gateway

{
  "messages": ["message.integration.connection.refused"]
}

Ocorre quando um serviço downstream está indisponível.

Exemplos por Domínio

Domínio	Erro Comum	Mensagem
Cadastros	Produtor não encontrado	message.producer.not-found
Cadastros	CPF/CNPJ duplicado	message.producer.already-exists
Comercial	Carteira não encontrada	message.wallet.not-found
Autenticação	Header ausente ou inválido	Authorization ausente ou inválido (401 sem body)