Erros NF-e / NFC-e
Referência de códigos de erro HTTP, erros de aplicação e rejeições da SEFAZ para facilitar a depuração da sua integração.
Erros HTTP
| Status | Nome | Descrição |
|---|---|---|
| 400 | Bad Request | Payload inválido ou campos obrigatórios ausentes. |
| 401 | Unauthorized | Header x-api-key ausente ou inválido. |
| 403 | Forbidden | Chave revogada, sem assinatura ativa, ou créditos esgotados. |
| 404 | Not Found | Invoice não encontrada ou não pertence ao projeto. |
| 422 | Unprocessable | Certificado ausente, município não configurado, ou pré-condição falhou. |
| 429 | Too Many Requests | Rate limit excedido. Aguarde Retry-After segundos. |
| 500 | Internal Error | Erro inesperado. Tente novamente com backoff exponencial. |
Erros de Aplicação
Estes códigos são retornados no campo error.code do body da resposta.
| Código | Descrição |
|---|---|
| CREDIT_LIMIT | Limite de notas mensais atingido. Upgrade de plano necessário. |
| CERT_MISSING | Nenhum certificado A1 válido encontrado para o projeto. |
| CERT_EXPIRED | Certificado A1 expirado. Faça upload de um novo em Configurações. |
| PAYLOAD_INVALID | Payload com campos obrigatórios ausentes ou inválidos. O campo campos na resposta lista os problemas específicos encontrados. |
Rejeições SEFAZ — cStat
Quando a SEFAZ rejeita uma NF-e, o campo cStat retorna um código de rejeição no webhook nfe.error e na resposta do endpoint de status.
| cStat | Descrição | Ação Recomendada |
|---|---|---|
| 100 / 150 | Autorizado o uso da NF-e (100) / Autorizado fora de prazo (150) | Emissão confirmada ✅ |
| 102 | Inutilização de número homologado | Numeração ou faixa inutilizada com sucesso via POST /api/v1/nfe/inutilizar ✅ |
| 135 / 155 | Evento registrado e vinculado à NF-e (135) / Cancelamento homologado fora de prazo (155) | Cancelamento homologado pela SEFAZ via POST /api/v1/nfe/cancelar (MOC 7.0 §5.9.4). A SEFAZ pode retornar cStat=155 ao homologar o cancelamento fora do prazo ordinário de 24h (ex.: janelas estendidas de SP, PR, RS e CE); a plataforma trata ambos como sucesso (status=cancelled), persiste cancelProt + procEventoNFe e dispara o webhook nfe.cancelled / nfce.cancelled ✅ |
| 218 / 573 | NF-e já está cancelada na base de dados da SEFAZ (218) / Duplicidade de Evento (573) | No fluxo de cancelamento (tpEvento=110111), indica que o cancelamento já consta registrado na SEFAZ. Tratado de forma idempotente pela plataforma como cancelamento confirmado (status=cancelled) ✅ |
| 136 | Evento registrado, mas não vinculado à NF-e | A SEFAZ registrou o evento, mas não o vinculou à NF-e. No fluxo de cancelamento, não confirma o cancelamento da nota: o status permanece issued e o retorno é gravado em errorMessage para diagnóstico. |
| 501 | Rejeição: Prazo de cancelamento superior ao previsto na Legislação | Rejeição definitiva de prazo na SEFAZ (Regra 2P12-14 do MOC 7.0). A API valida preventivamente a janela por UF antes de enfileirar (HTTP 422); se a rejeição ocorrer na transmissão à SEFAZ, a nota permanece com status=issued e o motivo é registrado em errorMessage. |
| 204 | Duplicidade de NF-e [nRec:...] | A nota com esta exata Chave de Acesso já foi autorizada na SEFAZ. O worker executa auto-reconciliação automática via NFeRetAutorizacao4 / NFeConsultaProtocolo4, recupera o <protNFe> oficial e promove a invoice para status=issued. |
| 206 / 241 / 256 / 662 | NF-e já está inutilizada na Base de Dados da SEFAZ | O número ou parte da faixa já foi inutilizado anteriormente na SEFAZ. O número não é reciclado; em novas emissões o contador avançará para o próximo número livre. |
| 563 | Já existe pedido de Inutilização com a mesma faixa de inutilização | Retorno idempotente da SEFAZ quando exatamente a mesma faixa já foi inutilizada e retorna nProt. Em POST /api/v1/nfe/inutilizar, é tratado como sucesso idempotente (HTTP 200, idempotent: true). |
| 207 | CNPJ do emitente não autorizado para emissão na WAN | Solicitar habilitação na SEFAZ da UF emitente |
| 209 | IE do emitente inválida para a UF | Corrigir a Inscrição Estadual em Configurações → Empresa |
| 213 | CNPJ-Base do Emitente difere do CNPJ-Base do Certificado Digital | Para emitentes Pessoa Jurídica (CNPJ numérico ou alfanumérico [0-9A-Z]{12}\d{2}), faça upload de um certificado digital e-CNPJ A1 cuja raiz de 8 caracteres coincida com o CNPJ do projeto. A plataforma valida essa correspondência de forma case-insensitive no momento do upload quando o documento ICP-Brasil está presente no certificado. |
| 225 | Falha no schema XML | Causas mais comuns: items[].descricao vazio, dest.endereco.codigoMunicipio zerado ou sem 7 dígitos, campos de endereço com menos de 2 caracteres. A API agora rejeita esses payloads com HTTP 400 antes do envio à SEFAZ. Se cStat 225 persistir, verifique campos customizados (cBenef, IE). |
| 227 | CPF do Emitente difere do CPF do Certificado Digital | Para Produtor Rural Pessoa Física (CPF), faça upload de um certificado digital e-CPF A1 cujo CPF de 11 dígitos coincida exatamente com o CPF do projeto. A plataforma valida essa correspondência no upload quando o documento ICP-Brasil está presente no certificado. |
| 228 / 703 | Data de Emissão muito atrasada (228) ou futura (703) | No campo dataEmissao (dhEmi), a NF-e modelo 55 permite retroatividade máxima de 30 dias (Regra B09-20) e tolerância futura máxima de 5 minutos (Regra B09-10). A API valida essa janela preventivamente com HTTP 400. |
| 504 / 505 / 506 | Data de Entrada/Saída posterior ao permitido (504), anterior ao permitido (505) ou menor que a Data de Emissão (506) | No campo opcional dataSaida (dhSaiEnt — exclusivo NF-e mod. 55), a data/hora deve estar na janela de ±30 dias em relação à transmissão (Regras B10-20 e B10-30) e, em notas de saída (tipoOperacao: 1), não pode ser anterior a dataEmissao (Regra B10-40). A API valida essas regras preventivamente com HTTP 400. |
| 244 / 495 | Série incompatível com emitente CPF em emissão própria (procEmi=0) | Conforme a NT 2018.001 (regras B26-10 e C02a-10), emitentes Pessoa Física (CPF / Produtor Rural) em emissão própria devem utilizar exclusivamente as séries da faixa 920 a 969 (padrão 920). A API valida essa regra preventivamente com HTTP 400. |
| 244 / 503 | Série incompatível com emitente CNPJ em emissão própria (procEmi=0) | Conforme as regras B26-10 e C02-30 do MOC 7.0, emitentes Pessoa Jurídica (CNPJ) em emissão própria devem utilizar séries da faixa 1 a 889 (padrão 1). As séries 920 a 969 são exclusivas de emitentes CPF. A API valida essa regra preventivamente com HTTP 400. |
| 278 / 279 | Código de Município do Local de Entrega inexistente (278) ou divergente da UF do Local de Entrega (279) | No grupo entrega (Regras G07-20 e G07-30), informe um codigoMunicipio (cMun) de 7 dígitos da tabela oficial do IBGE cujo prefixo de 2 dígitos corresponda à uf informada. A API valida o formato e o prefixo da UF preventivamente com HTTP 400. |
| 478 | Local da entrega não informado para faturamento direto de veículos novos | Conforme a Regra C18-20 do MOC 7.0, em NF-e normal de saída (finalidade: 1, tipoOperacao: 1) que contenha veículo novo com faturamento direto para consumidor final (items[].veiculoNovo.tipoOperacao: 2), é obrigatório informar o objeto entrega (Grupo G) com os dados da concessionária onde ocorrerá a entrega. A API valida essa regra preventivamente com HTTP 400. |
| 514 / 541 | CNPJ do Local de Entrega inválido (514) ou CPF do Local de Entrega inválido (541) | No grupo entrega (Regras G02-10 e G02a-10), informe um cnpj (14 posições numéricas ou alfanuméricas NT 2025.001) ou cpf (11 dígitos) com dígitos verificadores módulo 11 válidos. A API valida preventivamente com HTTP 400. |
| 515 | Código de Município do Local de Entrega deve ser 9999999 para UF entrega = EX | No grupo entrega (Regra G07-10), quando uf: "EX" (exterior), o código do município deve ser "9999999" e o município "EXTERIOR" (preenchidos automaticamente pela plataforma se omitidos). |
| 970 / 971 | Código de País inexistente no Local de Entrega (970) ou IE inválida/indevida no Local de Entrega (971) | No grupo entrega (Regras G11-10 e G15-10 / NT 2018.005), informe código de país BACEN válido (1058 para Brasil ou código estrangeiro quando uf: "EX") e Inscrição Estadual de 2 a 14 dígitos numéricos válida na UF de entrega (ou omita/"ISENTO"; proibida quando uf: "EX"). |
| 301 | IE do destinatário inválida para a UF | Corrigir IE ou omitir para consumidor final |
| 321 | NF-e de devolução de mercadoria não possui documento fiscal referenciado por item | A partir de 05/10/2026 (NT 2025.002, regra VC02-14), em notas de devolução (finalidade: 4, modelo: 55) a SEFAZ exige que a chave original e o item (nItem) sejam informados por item em items[].nfeReferenciada gerando <DFeReferenciado> dentro de <det>. Referenciamento apenas no cabeçalho <NFref> é rejeitado pela SEFAZ com cStat 321. |
| 322 | NF de Produtor referenciada com mês/ano de emissão inválido | No grupo refNFP (Regra BA12-10), o campo aamm deve ter 4 dígitos numéricos com mês entre 01 e 12, não podendo ser posterior ao ano/mês de emissão da NF-e nem anterior a 20 anos. A API valida essa regra com HTTP 400 antes do envio. |
| 351 | Valor do ICMS da Operação no CST=51 difere do produto BC e Alíquota | No diferimento (CST 51, Regra N16a-10), vICMSOp deve corresponder a round2(vBC × pICMS / 100) (tolerância máxima ±R$ 0,01). Omita valorIcmsOperacao para que a plataforma calcule automaticamente. |
| 352 | Valor do ICMS Diferido no CST=51 difere do produto Valor ICMS Operação e percentual diferimento | No diferimento (CST 51, Regra N16c-10), vICMSDif deve corresponder a round2(vICMSOp × pDif / 100) (tolerância máxima ±R$ 0,01). Omita valorIcmsDiferido para que a plataforma calcule automaticamente. |
| 353 | Valor do ICMS no CST=51 não corresponde à diferença do ICMS operação e ICMS diferido | No diferimento (CST 51, Regra N17-10), a plataforma calcula automaticamente vICMS = round2(vICMSOp - vICMSDif), garantindo consistência exata. |
| 532 | Total do ICMS difere do somatório dos itens | Ocorre quando <ICMSTot><vICMS> diverge da soma de <vICMS> dos itens (Regra W04-10). No CST 51, a plataforma soma apenas o ICMS efetivamente devido (vICMS), nunca a parcela diferida (vICMSDif). |
| 929 | Informado CST de diferimento sem as informações de diferimento | Em UFs que ativam a Regra N07-10 do MOC 7.0 (ou sempre que subcampos de diferimento como percentualReducaoBc, cBenefRBC, valorIcmsOperacao ou valorIcmsDiferido forem enviados), informe explicitamente percentualDiferimento (pDif) no item cst: "51" (aliquotaIcms é opcional e assume default 12% quando omitida). Quando todos os subcampos de diferimento são omitidos, a plataforma preserva o caminho legado de compatibilidade. |
| 1010 | NF-e com referenciamento de documento a nível de nota e a nível de item | A SEFAZ proíbe ter simultaneamente referenciamento de nota (<NFref> em <ide>) e referenciamento por item (<DFeReferenciado> em <det>). A plataforma previne essa rejeição suprimindo automaticamente o grupo <NFref> quando finalidade: 4. |
| 1072 | Duplicidade de documento referenciado por item | Mais de um item da NF-e referenciou exatamente a mesma chave de acesso e o mesmo número de item (nItem) do documento fiscal original. Garanta que cada item aponte para um nItem correspondente da nota original. |
| 354 | Informado grupo de Devolução de Tributos para NF-e que não tem finalidade de Devolução de Mercadoria | O grupo devolucaoTributos (ou impostoDevol) só é permitido quando finalidade: 4. Remova o grupo para notas de finalidade 1 (Normal), 2 (Complementar) ou 3 (Ajuste). A API valida essa regra com HTTP 400 antes do envio. |
| 390 | Nota Fiscal de Consumidor Eletrônica com grupo de Devolução de Tributos | O grupo devolucaoTributos (ou impostoDevol) é proibido em NFC-e (modelo: 65). Devoluções devem ser emitidas exclusivamente como NF-e (modelo: 55). A API valida essa regra com HTTP 400 antes do envio. |
| 387 / 388 | Código de Enquadramento Legal do IPI inválido (387) ou incompatível com o CST do IPI (388) | No grupo items[].ipi (Regras O06-10 e O09-10), informe codigoEnquadramento (cEnq) compatível com o CST: faixa 301–399 para Isenção (CST 02/52), 001–099 para Imunidade (CST 04/54), 101–199 para Suspensão (CST 05/55) ou "999" (padrão automático) para os demais CSTs (00, 01, 03, 49, 50, 51, 53, 99). A API valida as faixas da regra O09-10 preventivamente com HTTP 400. |
| 538 / 604 | Total do IPI (538) ou Total do II (604) difere do somatório dos itens | A plataforma calcula e totaliza automaticamente <ICMSTot><vIPI> (Regra W12-10) e <ICMSTot><vII> (Regra W11-10) a partir dos itens e os soma ao vNF (Regra W16-10), inclusive em NF-e de importação (CFOP 3xxx). |
| 742 | NFC-e com grupo do IPI | O grupo items[].ipi (Grupo O) é exclusivo de NF-e (modelo: 55) e proibido em NFC-e (modelo: 65, Regra O01-10). A API bloqueia preventivamente com HTTP 400. |
| 531 | Total da BC ICMS difere do somatório dos itens | Ocorre quando o somatório de <vBC> dos itens difere do total informado no grupo <ICMSTot><vBC> (Regra W03-10). Para optantes do Simples Nacional ou MEI com CSOSN 900 em devoluções, a plataforma totaliza o valor automaticamente a partir da v0.54.5. |
| 1023 / 1024 | cClassTrib inexistente ou incompatível com o CST IBS/CBS | Use um código de 6 dígitos da tabela cClassTrib vigente e confirme que os três primeiros dígitos correspondem ao CST informado. |
| 1104 | Base de cálculo IBS/CBS difere do somatório dos componentes | Confira produto, frete, seguro, despesas, desconto e os valores de ICMS, DIFAL, PIS e COFINS do item. A API calcula essa base automaticamente. |
| 1105 | Valor total do item RTC divergente | Não envie valores IBS/CBS calculados. Em 2025/2026 os tributos RTC não compõem vItem; a plataforma aplica essa transição automaticamente. |
| 1115 / 1119 | Grupo ou total IBS/CBS ausente/divergente | Informe items[].ibscbs conforme a obrigatoriedade fiscal. Quando o grupo existe em um item, a plataforma gera IBSCBSTot mesmo com valores zerados. |
| 391 | Dados do cartão/pagamento eletrônico ausentes | Resolvido automaticamente: o sistema gera grupo card com tipoIntegracao=2 para pagamentos eletrônicos. Verifique se worker está atualizado. |
| 410 | UF informada no campo cUF não é atendida pelo Web Service | Ocorre quando o documento fiscal é enviado para um Web Service autorizador que não atende a UF informada (ex: envio à SVRS em vez de autorizador próprio da UF). Roteamento resolvido automaticamente pela plataforma. |
| 434 | NF-e sem indicativo do intermediador | Ocorre quando presencaComprador é 2, 3, 4 (NFC-e entrega em domicílio) ou 9 e a tag <indIntermed> não foi gerada (Regra B25c-10, aplicável aos modelos 55 e 65). A plataforma mapeia indicadorIntermediador (com auto-default 0 para venda direta) tanto em NF-e quanto em NFC-e. |
| 435 | NF-e não pode ter indicativo do intermediador | Ocorre quando presencaComprador é 0, 1 ou 5 (presencial) e o campo indicadorIntermediador é enviado no XML (Regra B25c-20). A plataforma omite automaticamente a tag quando indicadorIntermediador: 0 em operação presencial e rejeita com HTTP 400 se indicadorIntermediador: 1. |
| 438 / 439 / 440 | Informações do intermediador da transação ausentes, indevidas ou com CNPJ inválido | Quando indicadorIntermediador: 1 (marketplace / plataforma de terceiros), informe obrigatoriamente intermediador: { cnpj, idCadIntTran } com CNPJ válido de 14 posições (numérico ou alfanumérico [0-9A-Z]{12}\d{2}) e identificador de 2 a 60 caracteres (Regras YB01-10, YB01-20 e YB02-10). A API valida com HTTP 400 antes do envio. |
| 539 | Duplicidade de NF-e, com diferença na Chave de Acesso [chNFe:...][nRec:...] | O número (nNF) e série já possuem outra NF-e autorizada na SEFAZ com Chave de Acesso diferente (ex.: emitido por outro sistema antes da migração). O worker preserva a mesma chave/XML em retries para evitar 539 em timeouts, bloqueia a reciclagem do número e extrai chNFe e nRec em errorMessage. Ajuste o último número emitido em Configurações → Numeração e inutilize eventuais números pulados com POST /api/v1/nfe/inutilizar. |
| 660 | Item com CFOP de combustível sem grupo combustível (comb) | Inclua o objeto items[].combustivel com pelo menos codigoAnp, descricaoAnp e ufConsumo. A API rejeita com HTTP 400 antes do envio à SEFAZ — inclusive na NFC-e, onde a regra LA01-20 é facultativa no MOC mas aplicada pela plataforma como política restritiva. |
| 461 | Percentuais GLP informados para produto que não é GLP | Os campos percentualGlp/percentualGnn/percentualGni só são aceitos para cProdANP = 210203001 (GLP). A API rejeita com HTTP 400. |
| 855 | Soma pGLP + pGNn + pGNi difere de 100 | Para GLP (210203001), os três percentuais devem somar exatamente 100. A API rejeita com HTTP 400. |
| 907 | pBio informado para produto que não aceita | O campo percentualBiodiesel (pBio) foi informado para um cProdANP cuja coluna pBio na Tabela de Combustíveis Monofásicos (IT 2023.003) é 0, ou para produto fora da tabela. Remova o campo. A API rejeita com HTTP 400. |
| 908 | pBio ausente para produto que exige | O campo percentualBiodiesel (pBio) é obrigatório para este cProdANP (coluna pBio=1 na IT 2023.003) em NF-e mod.55, exceto consumidor final, devolução/complementar e CFOP 5922/6922. A API rejeita com HTTP 400. |
| 909 | Grupo de origem do combustível ausente | Informe items[].combustivel.origemCombustivel quando a Tabela de Combustíveis Monofásicos indica origComb=1 para o codigoAnp, ou quando percentualGnn/percentualGni > 0 (GLP). Em NF-e mod.55, não se aplica a consumidor final, devolução/complementar nem CFOP 5922/6922. A API rejeita com HTTP 400. |
| 747 | Grupo de origem do combustível não permitido | O codigoAnp informado não consta da Tabela de Combustíveis Monofásicos — remova origemCombustivel. A API rejeita com HTTP 400. |
| 694 | Não informado cBenef para CST (PR/RS) | Incluir código de benefício fiscal para UFs que exigem |
Rejeições NFC-e — Específicas do modelo 65
Estas rejeições ocorrem exclusivamente em emissões de NFC-e (modelo 65) e estão relacionadas ao QR Code, CSC e regras de presença do comprador.
| cStat | Descrição | Ação Recomendada |
|---|---|---|
| 373 | Descrição do primeiro item diferente de NOTA FISCAL EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL | Em ambiente de homologação (tpAmb=2), a regra I04-10 do MOC 7.0 exige que a descrição do primeiro item da NFC-e seja exatamente este texto. Tratado automaticamente pela plataforma. |
| 464 | Hash do QR Code difere do calculado pela SEFAZ | Verificar se o CSC (ID + Token) está correto em Configurações → NFC-e. O hash é calculado sobre os campos + CSC, sem a URL base. |
| 600 | CSC inválido ou não cadastrado (NFC-e) | Verificar CSC ID e Token em Settings → NF-e. O CSC é obtido no portal SEFAZ da UF do emitente. |
| 705 | NFC-e com data de entrada/saída | Conforme a Regra B10-10 do MOC 7.0, a NFC-e (modelo: 65) não aceita o campo dataSaida (dhSaiEnt). Remova o campo ou emita como NF-e modelo 55. A API valida essa regra preventivamente com HTTP 400. |
| 717 | NFC-e em operação não presencial | Usar presencaComprador: 1 (presencial), 4 (delivery) ou 5 (fora do estabelecimento). Para e-commerce, usar NF-e modelo 55. |