Códigos de status interno

A API do FazNota adota uma convenção de canal único de status: enquanto a aplicação processar a requisição (passar autenticação e parser), a resposta é sempre HTTP 200, e o resultado real fica em body.status (3 dígitos, 001–999).

Esse código distingue sucesso, pendência, erro de validação, rejeição da SEFAZ e erros internos. Apenas falhas estruturais (auth, rate limit, URL errada) retornam HTTP ≠ 200 — veja Estrutura de resposta para o detalhe.

Enquanto processa, o status é 003 (pendente) — nunca reemita

Enquanto a SEFAZ ainda não respondeu (inclusive quando está lenta ou instável), a consulta do recibo devolve status: "003" (em processo de emissão) — pendente, não falha. Nosso sistema reconcilia automaticamente em até 3 horas. O status: "900" indica rejeição definitiva (corrija o dado e emita nova nota). Salvaguarda defensiva: se receber 900 com data.sefaz.codigo 217 ou 105, trate também como pendente — não reemita. Veja SEFAZ lenta ou instável — reemitir enquanto pendente gera duplicidade de documento fiscal.

Tabela completa

Código	Significado	Quando aparece
001	Registrado. A operação foi recebida e está na fila para processamento.	Resposta imediata de qualquer emissão/cancelamento/CC-e.
002	Pendente de processamento. Na fila, ainda não começou.	Polling do recibo logo após emissão.
003	Em processo de emissão. Está sendo processada agora.	Polling enquanto SEFAZ ainda não respondeu.
004	Documento emitido. Status terminal de sucesso.	Polling após autorização SEFAZ — data.sefaz.codigo 100, 120 (com alerta) ou 150 (fora de prazo). Veja Autorizada com alerta.
005	Consulta realizada. Status para endpoints GET de listagem/busca.	Listagens, buscas por documento/nome/referência.
010	Documento cancelado. Status terminal após cancelamento.	Polling após processamento de cancelamento.
050	Duplicidade de numero-origem. A operação não criou nova nota; retorna o recibo da emissão original.	Emissão com numero-origem já usado. Veja Idempotência.
500	Recibo não existe. O recibo informado não está na base.	GET /<recurso>/<recibo> com recibo inválido.
900	Rejeição definitiva da SEFAZ — corrija o dado apontado em sefaz.mensagem e emita nova nota. (O processamento aparece como 003, não 900. Salvaguarda: se vier 900 com sefaz.codigo 217/105, é transitório — trate como pendente. Veja SEFAZ lenta ou instável.)	Polling após SEFAZ recusar a nota (CST inválido, NCM errado, etc.).
999	Erro interno. Erro de validação do payload OU erro inesperado. Veja data.erro.	Imediatamente após qualquer requisição com erro.

Autorizada com alerta (cStat 120)

A partir de 05/10/2026 (NT 2026.002, “Autorização de Uso com Alerta”) a SEFAZ passa a devolver um terceiro código de autorização, 120 — “Autorizado o uso da NF-e, com alerta”. De início vale só para a NFC-e (modelo 65); a NF-e (55) pode adotar depois, e a API já trata os dois do mesmo jeito.

data.sefaz.codigo	data.sefaz.mensagem (texto da SEFAZ)	status
100	Autorizado o uso da NF-e	004
120	Autorizado o uso da NF-e, com alerta	004
150	Autorizado o uso da NF-e, autorização fora de prazo	004

120 é nota autorizada — guarde, imprima e entregue normalmente

O documento foi autorizado e está armazenado na SEFAZ, com chave e protocolo, exatamente como o 100. O status é o mesmo 004 (Documento emitido) e data.sefaz traz o bloco completo — chave, protocolo, url-danfe, url-xml. Não corrija, não cancele, não reemita.

O alerta é informativo: a SEFAZ avisa de algo que ela vai cruzar depois, sem impedir a autorização. Exemplo (regra 5E17-65): código 172, “Alerta: Situação do CNPJ destinatário inabilitado no momento da autorização”. Se a nota estiver fora de prazo e tiver alerta, a SEFAZ devolve 120 (e não 150).

Se o seu sistema decide “autorizada” comparando data.sefaz.codigo == "100", ajuste agora: use o status 004 (o critério recomendado), ou aceite 100, 120 e 150. Quem já olha só para o status não precisa mudar nada.

Hoje a API não devolve o código e o texto de cada alerta em campo próprio: data.sefaz.mensagem traz o motivo geral da SEFAZ (o xMotivo). Os alertas vêm no protocolo de autorização (protNFe/infProt, pares cMsg/xMsg, até 5).

Códigos por tipo de operação

Emissão (POST)

Imediatamente após enviar uma emissão (NFe, NFCe, NFSe):

Código	Cenário
001	OK, processando. Comece o polling.
050	numero-origem duplicado; use o recibo retornado.
999	Erro de validação (veja data.erro).

Consulta de recibo (GET)

Durante o polling do recibo:

Código	Cenário	Ação
001	Acabou de ser registrada.	Aguarde, consulte novamente.
002	Pendente.	Aguarde, consulte novamente.
003	Emitindo.	Aguarde, consulte novamente.
004	Emitida ✅	Pegue data.sefaz.url-danfe e data.sefaz.url-xml. Vale para sefaz.codigo 100, 120 (autorizada com alerta) e 150.
010	Cancelada	Não emita de novo.
500	Recibo inválido.	Verifique se o recibo foi salvo corretamente.
900	Rejeitada SEFAZ (definitiva)	Corrija o dado indicado em data.sefaz.mensagem e emita nova nota. (O processamento em andamento aparece como 003, não 900. Salvaguarda: se vier 900 com data.sefaz.codigo 217/105, aguarde e consulte de novo, não reemita — veja SEFAZ lenta ou instável.)
999	Erro interno.	Cite meta.request_id no suporte.

Listagem (GET)

Código	Cenário
005	OK. data traz a lista.
999	Erro interno.

Cancelamento / Carta de correção (POST)

Imediatamente após enviar:

Código	Cenário
001	OK, processando. Comece o polling em GET /<recurso>/cancelamento/{recibo} ou GET /<recurso>/correcao/{recibo}.
999	Erro de validação.

Padrão para clientes

003 é pendente; 900 é rejeição definitiva (com salvaguarda 217/105)

Enquanto processa, o status é 003 (pendente) — continue consultando, nunca reemita. O 900 é rejeição definitiva. Salvaguarda defensiva: se data.sefaz.codigo for 217 ou 105, a SEFAZ ainda está processando — trate como pendente, nunca como falha. Reemitir enquanto pendente duplica o documento fiscal. Veja SEFAZ lenta ou instável.

const TERMINAIS_SUCESSO = ['004', '010'];
const TERMINAIS_FALHA = ['500', '999']; // "900" tratado à parte — veja abaixo
const PENDENTES = ['001', '002', '003'];
const SEFAZ_CODIGO_TRANSITORIO = ['217', '105']; // SEFAZ lenta: não é rejeição definitiva

function classificar(json: { status: string; data?: { sefaz?: { codigo?: string } } }): 'sucesso' | 'falha' | 'pendente' {
  const { status, data } = json;

  if (status === '900') {
    const codigoSefaz = data?.sefaz?.codigo;
    // SEFAZ lenta/instável: ainda não é definitivo, continue consultando o mesmo recibo
    if (codigoSefaz && SEFAZ_CODIGO_TRANSITORIO.includes(codigoSefaz)) return 'pendente';
    return 'falha'; // rejeição real — corrija o dado e emita nova nota
  }

  if (TERMINAIS_SUCESSO.includes(status)) return 'sucesso';
  if (TERMINAIS_FALHA.includes(status)) return 'falha';
  if (PENDENTES.includes(status)) return 'pendente';
  if (status === '050') return 'sucesso'; // duplicidade é retorno controlado
  if (status === '005') return 'sucesso'; // consulta OK
  return 'falha';
}