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 por item | Em cada item da devolução, informe items[].nfeReferenciada com chaveAcesso e o nItem da NF-e original. Não informe refNFe na raiz. |
| 1010 | NF-e com referenciamento no nível da nota e do item | Não combine refNFe/nfesReferenciadas na raiz com items[].nfeReferenciada. Em devoluções, mantenha somente a referência por item. |
| 1048 / 1102 | Número do item original não informado no DFeReferenciado | Informe nItem como inteiro entre 1 e 999, usando o atributo det/@nItem do XML original. A posição do produto na devolução atual não substitui esse valor. |
| 1072 | DFe/item referenciado em duplicidade | Não repita a mesma combinação de chaveAcesso e nItem em mais de um item da nota. |
| 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. |
| 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. |
| 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 |
|---|---|---|
| 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. |
| 708 | NFC-e não pode referenciar documento fiscal por item | Remova items[].nfeReferenciada. O grupo DFeReferenciado é suportado apenas em NF-e modelo 55. |
| 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. |