NFER
Visão GeralQuick StartAutenticaçãoAmbientesConfiguração InicialExemplos de RequisiçãoGlossário FiscalChecklist de Go-LiveFAQModelo de DadosCiclo de Vida & FluxoContingência AutomáticaLimites & Rate LimitEvitando DuplicidadeErros e RetransmissãoSplit Fiscal HíbridoNovoConceitosEmissão Passo a PassoConceitosEmissão Passo a PassoConceitosEmissão Passo a PassoCódigos de ServiçoConceitosEmissão Passo a PassoNovoRegimes, CST e CFOPEventos FiscaisVisão Geral & CronogramaNovos Campos na APITabela cClassTribDevoluções & AnulaçõesChecklist de MigraçãoVisão Geral & NSUCorporate+NF-e Recebidas & MD-eCorporate+NFS-e Tomadas (ADN)Corporate+CT-e Fretes & DesacordoCorporate+White-Label & Org APIEmpresaCertificado A1 & CSCHabilitação SEFAZCadastrosNumeraçãoPlanos

Tratamento de Erros e Retransmissão

Distinção entre falhas HTTP e rejeições SEFAZ cStat; quando corrigir e quando inutilizar.

Para construir uma integração robusta e livre de travamentos no PDV ou faturamento, é indispensável separar com clareza as falhas de requisição HTTP das rejeições fiscais da SEFAZ. Cada tipo de erro exige um tratamento diferente no seu sistema.

1. Erros HTTP (Camada de Transporte e Schema)

Ocorrem de forma síncrona na hora em que seu cliente faz o disparo para a API do NFER:

Código HTTPOrigemAção Recomendada
400 Bad RequestPayload JSON inválido, tipos incompatíveis ou campos obrigatórios ausentes.Inspecione o array de validação retornado e corrija os tipos no seu JSON antes de tentar novamente.
401 UnauthorizedCabeçalho X-API-Key ausente, expirado ou revogado.Verifique se a chave de API da empresa está configurada corretamente no seu arquivo .env.
403 ForbiddenEmpresa suspensa, sem certificado A1 configurado ou restrição de tenant.Valide o status da empresa emissora e certifique-se de que o certificado digital está carregado.
429 Too Many RequestsLimite de requisições por minuto excedido.Aguarde os segundos indicados no cabeçalho Retry-After e implemente backoff exponencial.
500 / 502 / 503Instabilidade momentânea de infraestrutura.Repita a requisição após alguns segundos utilizando o mesmo identificador previamente salvo.

2. Rejeições Fiscais da SEFAZ (cStat)

Ocorrem durante o processamento assíncrono. Seu payload é sintaticamente válido, mas a Secretaria da Fazenda rejeita as regras de tributação ou cadastro da nota:

  • A nota muda para o status erro no banco de dados.
  • O NFER preenche os campos erroCstat (código numérico) e erroMotivo (motivo textual do fisco).
  • O webhook com evento nfe.erro é enviado ao seu servidor com os detalhes.

Fluxo de Decisão: Corrigir vs Inutilizar

Quando Corrigir e Reenviar (PUT + Send)

A imensa maioria das rejeições é de dados corrigíveis (ex.: CPF inválido, NCM descontinuado na tabela TIPI, CST incompatível com Simples Nacional).

  1. Edite os campos rejeitados via PUT /v1/nfe/:id.
  2. Reenvie a mesma nota via POST /v1/nfe/:id/send.
  3. A numeração fiscal original é preservada sem gerar furos na série.

Quando Inutilizar a Numeração

Se uma numeração foi pulada por erro de sistema, ou se o pedido foi cancelado e a nota rejeitada não puder mais ser reaproveitada:

  1. Exclua o rascunho com falha via DELETE /v1/nfe/:id.
  2. Chame POST /v1/nfe/inutilization informando série, número e justificativa mínima de 15 caracteres.
  3. A SEFAZ formaliza que aquele número foi descartado perante a contabilidade.

Consulte o Catálogo Completo de cStat

Para ver o significado e a solução passo a passo dos códigos de rejeição mais comuns da SEFAZ, acesse a página de Erros e Rejeições Fiscais.
AnteriorEvitando DuplicidadePróximoSplit Fiscal Híbrido