Tratamento de Erros

Rejeições SEFAZ

Para NF-e, CT-e e MDF-e, o resultado da SEFAZ chega em dois campos padronizados nacionalmente: cStat (código numérico) e xMotivo (texto).

⚠️

A CentralFiscal não traduz nem filtra esses códigos. O motor lê cStat/xMotivo direto da resposta da SEFAZ e repassa sem alteração em detalhes.cstat e detalhes.xmotivo na resposta da API. Não existe hoje um catálogo interno nosso mapeando cada código pra uma mensagem amigável -- xMotivo já vem em português, direto da SEFAZ, e é isso que você vê.

Onde encontrar

{
  "status": "REJECTED",
  "mensagem": "Rejeicao: Duplicidade de NF-e",
  "detalhes": {
    "cstat": "539",
    "xmotivo": "Rejeicao: Duplicidade de NF-e"
  }
}

Faixas de código (padrão nacional)

O cStat segue uma convenção nacional (Manual de Orientação do Contribuinte, publicado pela SEFAZ/ENCAT -- vale para NF-e, CT-e e MDF-e, mesma numeração base) por faixa de centena:

Faixa	Significado geral
`1xx`	Autorização -- ex.: `100` Autorizado o uso.
`2xx`/`3xx`	Denegação -- ex.: `110` Uso Denegado (irregularidade fiscal do emitente/destinatário).
`5xx`	Rejeição -- schema inválido, regra de negócio violada, duplicidade -- ex.: `539` Rejeição: Duplicidade de NF-e.
`9xx`	Erro interno da SEFAZ (não é erro do seu payload) -- ex.: `999` Erro não catalogado.

💡

Esses 4 exemplos (100, 110, 539, 999) são os mais citados na prática, mas a lista completa tem centenas de códigos e varia por documento (NF-e/CT-e/MDF-e) e por UF em alguns casos pontuais. A fonte oficial é sempre o Manual de Orientação do Contribuinte publicado pela SEFAZ da UF do emitente -- trate xMotivo (o texto) como a informação confiável no dia a dia, e use cStat só pra automação simples (ex.: == "100" como sucesso).

Como tratar no seu ERP

Sucesso: status == "AUTHORIZED" (equivale a cStat 100).
Rejeição corrigível (dados do seu payload): status == "REJECTED" -- mostre xmotivo pro usuário, corrija e reenvie (pode reusar a mesma Idempotency-Key só depois de corrigir o payload -- reenviar igual devolve o mesmo resultado rejeitado, não tenta de novo).
Denegação: também REJECTED, mas a causa é cadastral (CNPJ/IE irregular) -- não adianta reenviar sem resolver a pendência fora da API primeiro.
Erro interno SEFAZ (9xx): status == "ERROR" -- aguarde e reenvie depois; não é um problema do seu payload.