Como pensar erros da SEFAZ (rejeição vs indisponibilidade)
Rejeição fiscal (o SEU dado) e indisponibilidade da SEFAZ (o serviço DELES) chegam por caminhos diferentes na engineAPI — entenda a diferença antes de decidir se o problema é seu ou é retry.
Como pensar erros da SEFAZ
Nem todo erro que envolve a SEFAZ é do mesmo tipo. A engineAPI separa dois problemas que se parecem, mas pedem reações opostas.
Rejeição: o problema é o SEU dado
A SEFAZ recebeu o XML, processou, e recusou por causa do conteúdo — CNPJ inválido,
NCM inexistente, duplicidade de número, certificado vencido. Chega como HTTP 400
com error.erros[] — o código e a mensagem da SEFAZ, verbatim, sem tradução (ex.:
{ "codigo": "539", "descricao": "Rejeicao: Duplicidade de NF-e" }). Reenviar o mesmo
payload sem corrigir o campo apontado gera a mesma rejeição de novo — não é um caso de
retry.
Indisponibilidade: o problema é o serviço DELES
O webservice da SEFAZ do estado está fora do ar ou em manutenção (cStat 108/109).
Aqui a engineAPI não te devolve um 400 pra você resolver — ela reroteia
automaticamente a transmissão para a SEFAZ Virtual de Contingência (SVC-AN ou
SVC-RS). O documento chega a AUTHORIZED do mesmo jeito; o único rastro é o tpEmis
no XML autorizado. Consultar GET /v1/nfe/sefaz-status/{uf} (ou o status
público) antes de emitir ajuda a
antecipar isso, mas a contingência já cobre automaticamente sem ação do parceiro.
A status page pública (GET /v1/status, sem autenticação — consumida em
status.engineapi.com.br) trata isso como conceitos separados: o rollup de NFSe compara
AUTHORIZED vs ERROR explicitamente sem contar rejeição fiscal do cliente como
indisponibilidade da engineAPI — são eixos diferentes por desenho.
Na prática
| | Rejeição | Indisponibilidade |
|---|---|---|
| Quem errou | O dado enviado | O webservice da SEFAZ |
| Status HTTP | 400 | Não aparece como erro — reroteada pra contingência |
| Campo no envelope | error.erros[] (verbatim) | — |
| Ação certa | Corrigir o campo apontado | Nenhuma — a engineAPI já reroteou |
| Retry cego ajuda? | Não — repete o mesmo erro | Não se aplica (já resolvido via SVC) |