Erros

A API pode devolver erro em 3 formatos diferentes de corpo, dependendo de onde o erro se origina. Os SDKs oficiais normalizam os 3 formatos numa única exceção (NFeApiError no Node/Python, NFeApiException no Java) — mas se você estiver integrando via REST puro, vale conhecer as variações.

1. Erro de validação da própria API

Formato padrão para erros de autenticação, limite de plano, parâmetro obrigatório ausente, etc. message é uma string.

{
  "statusCode": 401,
  "message": "Chave de API (Bearer Token) ausente ou inválida.",
  "error": "Unauthorized"
}

A mesma forma é usada quando falta ou é inválida a Chave de Acesso (X-Access-Key) — veja Autenticação para os dois formatos de erro de auth.

2. Erro de validação de schema do documento fiscal

Quando o corpo de emit (ou de um evento) não bate com o schema esperado para aquele mod, message vem como objeto, não string — contém a lista detalhada de campos inválidos.

{
  "statusCode": 400,
  "message": {
    "message": "Dados inválidos",
    "errors": {
      "natureza_operacao": "Required",
      "itens": "Required"
    }
  },
  "error": "Bad Request"
}

3. Erro de negócio genérico

Alguns erros (ex: saldo de créditos insuficiente) não passam por um formatador de exceção e chegam como 500 genérico — a mensagem original de negócio não é recuperável a partir do corpo da resposta nesse caso.

{
  "statusCode": 500,
  "message": "Internal server error"
}

Se você receber um 500 sem detalhe, é um bom sinal para tentar novamente com backoff e, se persistir, abrir um chamado de suporte informando o invoiceId/horário da tentativa.

Emissão, cancelamento e correção não retornam erro de negócio de forma síncrona

Como emit, cancel e correct são processados em fila, uma emissão que passa na validação inicial mas é rejeitada pela SEFAZ não gera um erro HTTP — a chamada retorna 202 Accepted normalmente. O motivo da rejeição só aparece consultando o documento (GET /v1/nfe/{id}, campo rejectionReason). Sempre faça polling em vez de assumir sucesso a partir do 202.