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.

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.

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
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.
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

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.
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.