Erros

Quando ocorre um erro, a API retorna uma lista de objetos contendo um código e uma mensagem descritiva.

[
  {
    "codigo": "MONITORAMENTO_INATIVO",
    "mensagem": "O monitoramento de NF-e não está ativo para esta empresa."
  }
]

O campo codigo identifica o erro e deve ser utilizado pela sua aplicação.

O campo mensagem é destinado à exibição para usuários e ao diagnóstico, podendo sofrer alterações de texto ao longo do tempo.

---

Sempre trate a resposta como uma lista

Mesmo quando existe apenas um erro, a resposta continua sendo um array.

Isso permite que uma mesma requisição retorne múltiplos problemas de validação.

[
  {
    "codigo": "CAMPO_OBRIGATORIO",
    "mensagem": "O campo empresaId é obrigatório."
  },
  {
    "codigo": "DATA_INVALIDA",
    "mensagem": "A data informada é inválida."
  }
]

---

Códigos HTTP

A API utiliza os códigos HTTP convencionais para indicar o resultado da requisição.

Status	Significado
400 Bad Request	A requisição contém dados inválidos.
401 Unauthorized	A credencial é inválida ou não possui acesso ao recurso solicitado.
404 Not Found	O recurso solicitado não foi encontrado.
409 Conflict	A operação não pode ser executada devido ao estado atual do recurso.
429 Too Many Requests	O limite de requisições foi excedido.
5xx	Ocorreu um erro interno ou uma indisponibilidade temporária.

---

Retentativas

Nem todo erro deve ser tratado da mesma forma.

Situação	Recomendação
400, 401, 404 e 409	Corrija a requisição antes de tentar novamente.
429	Aguarde o tempo indicado pela API antes de realizar uma nova tentativa.
5xx	Realize novas tentativas utilizando backoff exponencial.

---

Boas práticas

• Utilize o campo codigo para tomar decisões na aplicação.
• Utilize o campo mensagem apenas para exibição ou diagnóstico.
• Registre o corpo da requisição e da resposta em seus logs para facilitar a investigação de falhas.