Erros SEFAZ traduzidos

A SEFAZ retorna códigos numéricos (cStat) com mensagens terrivelmente técnicas em XML. O gateway traduz isso pra português humano + sugestão de fix, antes de devolver via API ou webhook.


{
  "status": "denied",
  "error": {
    "cStat": 778,
    "xMotivo": "Rejeição: NCM com dígito inválido",
    "humanized": "O NCM do item 3 (descrição: 'Camisa Algodão') tem dígito de verificação inválido. NCM válido tem 8 dígitos numéricos.",
    "fix_suggestion": "Verifique o cadastro do produto. NCM correto pra camisa de algodão = '61091000'. Consulte tabela TIPI.",
    "item_index": 2,
    "field": "ncm"
  }
}

Top 20 erros mais comuns

cStat	xMotivo SEFAZ	Tradução humana	Fix
204	Duplicidade de NF-e	Chave de acesso já autorizada	Use GET pra recuperar
215	Falha schema XML	Campo obrigatório ausente	Veja `error.field`
217	Não consta no cadastro SEFAZ	NF-e/protocolo não existe	Confira a chave
225	Falha NCM inválido	NCM não bate com tabela TIPI	Atualize cadastro
233	Chave de acesso inválida	Dígito verificador errado	Geração interna (bug)
239	Modelo ≠ 65 inválido pra NFC-e	Tentou emitir mod 55 como NFC-e	Use `/v1/nfe`
250	Certificado expirado	Cert A1 vencido	Renove + upload novo
252	Ambiente diferente	Cert prod com homolog (ou vice-versa)	Veja `ambiente` no Issuer
280	Certificado revogado	CRL marca cert como inválido	Renove
282	Não corresponde ao CNPJ	Cert é de outro CNPJ	Use cert correto
297	CPF/CNPJ inválido	Dígito errado	Valide antes
301	Uso denegado	Emitente irregular SEFAZ	Regularize cadastro
302	Destinatário irregular	IE destinatário cancelada/baixada	Confira no SINTEGRA
422	NFC-e fora SP	Tentou usar URL SP em outra UF	Verifique `Issuer.uf`
509	Erro 999 (genérico SEFAZ)	Erro interno SEFAZ — retry em 30s	Worker retenta automaticamente
539	Duplicidade de NF-e	Mesma chave + mesma SEFAZ	Use Idempotency-Key
656	Consumo indevido SEFAZ	Rate-limit da SEFAZ atingido	Reduza requests / use sandbox
778	NCM inválido	Veja 225 acima	Idem
999	Rejeição genérica	Erro não catalogado	Abra ticket no suporte

Quando o gateway não consegue traduzir

Pra códigos novos ou raros, devolve:


{
  "error": {
    "cStat": 999,
    "xMotivo": "Rejeicao: <raw SEFAZ message>",
    "humanized": "Erro SEFAZ não traduzido (cStat=999). Mensagem original: '<raw>'.",
    "fix_suggestion": "Abra ticket em support@zfiscoo.zek.app.br com a access_key. Vamos catalogar.",
    "raw_xml_url": "https://api.zfiscoo.zek.app.br/v1/nfce/nfce_.../sefaz-raw-response"
  }
}

O raw_xml_url te dá acesso à resposta original da SEFAZ — útil pra debug fundo e pra reportar pro suporte.

Como o catálogo é mantido

Fonte canônica em packages/fiscal-core/src/sefaz-errors.ts — open source, MIT. PR’s são bem-vindos.

🤝

Se você bater num cStat não catalogado em produção, abra um issue no GitHub com a access_key. Adicionamos ao catálogo em horas, libera pra toda comunidade.