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.). 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.