Pular para o conteúdo

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.


Tabela completa

CódigoSignificadoQuando aparece
001Registrado. A operação foi recebida e está na fila para processamento.Resposta imediata de qualquer emissão/cancelamento/CC-e.
002Pendente de processamento. Na fila, ainda não começou.Polling do recibo logo após emissão.
003Em processo de emissão. Está sendo processada agora.Polling enquanto SEFAZ ainda não respondeu.
004Documento 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.
005Consulta realizada. Status para endpoints GET de listagem/busca.Listagens, buscas por documento/nome/referência, classificação fiscal, leitura de rotinas.
010Documento cancelado. Status terminal após cancelamento.Polling após processamento de cancelamento.
050Duplicidade 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.
500Recibo não existe. O recibo informado não está na base.GET /<recurso>/<recibo> com recibo inválido.
900Rejeiçã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.).
999Erro 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.codigodata.sefaz.mensagem (texto da SEFAZ)status
100Autorizado o uso da NF-e004
120Autorizado o uso da NF-e, com alerta004
150Autorizado o uso da NF-e, autorização fora de prazo004

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ódigoCenário
001OK, processando. Comece o polling.
050numero-origem duplicado; use o recibo retornado.
999Erro de validação (veja data.erro).

Consulta de recibo (GET)

Durante o polling do recibo:

CódigoCenárioAção
001Acabou de ser registrada.Aguarde, consulte novamente.
002Pendente.Aguarde, consulte novamente.
003Emitindo.Aguarde, consulte novamente.
004Emitida ✅Pegue data.sefaz.url-danfe e data.sefaz.url-xml. Vale para sefaz.codigo 100, 120 (autorizada com alerta) e 150.
010CanceladaNão emita de novo.
500Recibo inválido.Verifique se o recibo foi salvo corretamente.
900Rejeitada 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.)
999Erro interno.Cite meta.request_id no suporte.

Listagem (GET)

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

Cancelamento / Carta de correção (POST)

Imediatamente após enviar:

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

Classificação fiscal (POST)

Resposta na mesma chamada, sem recibo. Veja Classificação fiscal.

CódigoCenário
005Classificado (data.pacote). No lote, o pedido foi aceito: confira o status de cada item em data.resultados.
400Pedido fora do formato ou recusado pelo motor. Motivo na descricao, campo em data.campo.
999Motor indisponível ou item que não terminou no prazo do lote. Tente de novo.

Certificado digital

Resposta na mesma chamada, sem recibo. Veja Certificado digital A1.

CódigoCenário
005GET /certificado: situação e validade do certificado.
001POST /certificado/a1: certificado instalado e já em uso.
400Campo ausente ou inválido (data.campo), senha errada, arquivo que não é A1 ICP-Brasil, certificado vencido, de outro CNPJ/CPF ou que vence antes do atual.
999Falha interna ao falar com o módulo de certificado, ou limite de instalações por minuto. Tente de novo.

Rotinas

Resposta na mesma chamada, sem recibo. Veja Rotinas.

CódigoCenário
005Leitura (GET /rotinas...) e POST /rotinas/validar.
001Gravação ou ação concluída: criar, alterar, excluir, pausar, retomar, emitir agora, valores extras. No emitir-agora, a NFS-e foi enfileirada: o recibo aparece no histórico da rotina.
400Campo fora do formato (data.campo), regra do módulo, pendências que impedem ativar ou retomar (data.pendencias) ou chave sem permissão fiscal.
500Rotina não encontrada nesta empresa.
999Falha interna ao falar com o módulo de rotinas. Tente de novo.

CT-e e CT-e OS

Emissão, cancelamento, carta de correção e eventos entram na fila e devolvem recibo. Veja Emitir CT-e.

No POST:

CódigoCenário
001Pedido na fila (data.recibo). Com numero-origem já usado, é o recibo original (na fila ou já autorizado).
400Recusado na porta: campo obrigatório ausente ou fora do formato (data.campo), CT-e/recibo/chave que não é desta empresa ou não é do modelo da rota, CT-e não autorizado ou já cancelado, certificado A3 ou ausente, empresa sem RNTRC no modal rodoviário. Nada foi enfileirado.
999Falha interna ao registrar. Tente de novo.

No GET /cte/{recibo} e GET /cte-os/{recibo}:

CódigoCenário
002Na fila, ainda não processado. Continue o polling.
004Emissão autorizada (chave, protocolo, numero, serie, modelo, tp-amb, dh-recbto) ou evento registrado pela SEFAZ (tp-evento, protocolo).
010O CT-e está cancelado (protocolo-cancelamento).
900Recusado: pela SEFAZ (c-stat, x-motivo) ou pela validação do processamento (c-stat vazio). Corrija e reenvie — com o mesmo numero-origem, a emissão corrige o mesmo CT-e.
999Erro técnico ou desfecho indeterminado (data.erro). Reenvie o mesmo pedido.
500Recibo inexistente nesta empresa, de outro documento, ou do outro modelo (recibo de CT-e OS em /cte, e vice-versa).

BP-e (bilhete de passagem)

Assíncrono, com recibo. Veja Emitir BP-e.

No POST (emissão, substituição, cancelamento e eventos):

CódigoCenário
001Registrado na fila (ou, com o mesmo numero-origem, o recibo original). Comece o polling em GET /bpe/{recibo}.
400Pedido recusado na hora: campo ausente ou fora do formato (data.campo), empresa sem certificado A1, sem ambiente SEFAZ ou sem inscrição estadual, bilhete de outra empresa, não autorizado ou já cancelado. No reenvio de um numero-origem cuja tentativa anterior ainda está em andamento (data.campo = numero-origem): aguarde e reenvie o mesmo pedido.
999Erro interno. Tente de novo.

No GET /bpe/{recibo}:

CódigoEmissão / substituiçãoEventos
002 / 003Na fila / sendo emitido. Aguarde.Na fila / sendo enviado.
004Autorizado: chave, protocolo, qr-code.Evento registrado (c-stat 135/136).
010Autorizado e depois cancelado.Cancelamento registrado.
900Recusado pela SEFAZ (c-stat/x-motivo) ou pela validação do serviço (data.erro). Corrija e reenvie com o mesmo numero-origem.Evento recusado (c-stat/x-motivo).
999Erro técnico ou resultado indeterminado. Reenvie com o mesmo numero-origem: o bilhete já numerado é consultado na SEFAZ antes (adotado se autorizado, reemitido com o mesmo número se não consta).Erro técnico.
500Recibo inexistente ou de outra empresa.Idem.

MDF-e

Emissão e eventos devolvem 001 com o recibo, ou 400 quando o pedido é recusado na hora (motivo em data.erro). A consulta GET /mdfe/{recibo} responde pelo estado atual do manifesto. Veja Emitir MDF-e.

Códigodata.situacaoCenárioAção
002NA_FILANa fila.Aguarde, consulte novamente.
002AGUARDANDO_ASSINATURA_A3Montado; falta assinar com o certificado A3.O operador assina no aplicativo assinador. Não reenvie.
003PROCESSANDOSendo processado junto à SEFAZ.Aguarde, consulte novamente.
004AUTORIZADOAutorizado. data.viagem: ABERTA ou ENCERRADA. Nos recibos de inclusão, data.evento.Guarde chave e protocolo. Encerre ao fim da viagem.
004ENCERRADORecibo do encerramento: manifesto encerrado.—
010CANCELADOCancelado (recibo do cancelamento, ou da emissão de manifesto cancelado depois).Não reenvie.
900REJEITADORecusado pela SEFAZ (data.erro, data.c-stat) ou pela conferência antes de transmitir (data.pendencias).Corrija e reenvie — pode ser com o mesmo numero-origem.
999ERROErro técnico (comunicação, SEFAZ fora do ar).Emissão: reenvie o mesmo manifesto com o mesmo numero-origem (o mesmo rascunho é retransmitido). Evento: envie a mesma operação de novo.
500—Recibo inexistente ou de outra empresa.Verifique o recibo.

Padrão para clientes

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';
}