Erros e status (v2)
HTTP status
A v2 não usa HTTP status para sinalizar erro de negócio: os endpoints de negócio retornam sempre 200, e o resultado real está no corpo. As exceções são:
- Health (
/health*) — retorna status real (200/503). - Autenticação e roteamento — retornam status real (
401,403,404,405,429).
Formato das respostas (varia por endpoint)
A v2 não tem um envelope uniforme. O formato depende do endpoint:
| Situação | Corpo |
|---|---|
| Emissão aceita | { "recibo": "...", "status": "emitindo", "sefaz": { "codigo": "105", "mensagem": "Lote em processamento" } } |
| Nota pendente (polling) | { "status": "pendente", "sefaz": { "codigo": "9999", "mensagem": "Sua nota ainda não foi processada." } } |
| Nota pronta | Objeto da nota com bloco sefaz (chave, protocolo, url-danfe, url-xml) |
| Erro de negócio | { "erro": "<mensagem>" } (às vezes com id/numero/recibo adicionais) |
| CRUD (cliente/produto) | { "mensagem": "... com sucesso.", "id": "..." } |
| Erro de auth/roteamento | { "error": { "status": <n>, "message": "..." } } |
Mensagens de validação
Mensagens de validação vêm como texto livre em português, com a notação recurso@campo. Exemplos:
Campo nfe@serie não pode ser vazio.Campo nfe@cfop inválido.Campo nfe@chave deve ter 44 caracteres.Campo nfe@motivo deve ter entre 15 e 255 caracteres.
A mensagem de erro é sanitizada (remove HTML/scripts, limita a 500 caracteres) e sempre sai como JSON válido.
Status da nota (polling)
O campo status na consulta reflete o estado da nota:
status | Significado |
|---|---|
pendente | Cupom criado, ainda não enviado à SEFAZ |
processando | XML já enviado à SEFAZ, aguardando retorno |
emitindo | Em processamento (lote enviado) |
emitida | Autorizada pela SEFAZ (bloco sefaz preenchido) |
cancelada | Cancelada |
reescrita | Nota reescrita |
Além disso, o bloco sefaz.codigo/sefaz.mensagem traz o código/motivo da SEFAZ quando aplicável
(ex.: 100 = autorizado, rejeições etc.). Autorizada é 100, 120 ou 150: a partir de
05/10/2026 a SEFAZ passa a devolver 120 — “Autorizado o uso da NF-e, com alerta”, de início só
na NFC-e. A nota está autorizada (status: "emitida", bloco sefaz completo com chave, protocolo e
URLs); o alerta é informativo e não pede correção nem reenvio. 150 é a autorização fora de prazo.
Se o seu código compara sefaz.codigo == "100", passe a aceitar os três. Atenção: sefaz.codigo 217 ou 105 junto de
status: "emitindo" não é uma rejeição — é a SEFAZ ainda processando. Veja
SEFAZ lenta ou instável antes de decidir reemitir uma nota.
Rate limit
A v2 aplica limite de consumo por empresa. Ao exceder, você recebe HTTP 429 com uma mensagem informando quando o consumo volta a ser liberado.