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 | Autorizado o uso da NF-e | Emissão confirmada ✅ |
| 204 | Uso denegado — CNPJ emitente com irregularidade fiscal | Verificar situação fiscal do emitente na Receita Federal |
| 206 | NF-e já autorizada (duplicidade de chave) | Nota com mesma chave de acesso já foi autorizada. Consultar status para obter protocolo existente. |
| 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 |
| 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). |
| 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 | Informe refNFe/nfesReferenciadas (ou items[].nfeReferenciada, que alimenta o mesmo campo) com a chave de 44 dígitos da NF-e original no cabeçalho da nota. |
| 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. |
| 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 ou 9 (não-presencial) e o campo indicadorIntermediador foi omitido. O sistema aplica 0 automaticamente a partir da v0.52.20. Se persistir, atualizar o payload com indicadorIntermediador: 0 (venda direta) ou 1 (marketplace). |
| 435 | NF-e não pode ter indicativo do intermediador | Ocorre quando presencaComprador é 0, 1 ou 5 (presencial) e o campo indicadorIntermediador foi informado. Remover o campo para operações presenciais. |
| 539 | Duplicidade de número de NF-e | Inutilizar faixa e reemitir com novo número. Comum ao migrar de outro sistema emissor. |
| 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. |
| 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. |