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ó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, classificação fiscal, leitura de rotinas. |
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 |
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. |
Classificação fiscal (POST)
Resposta na mesma chamada, sem recibo. Veja Classificação fiscal.
| Código | Cenário |
|---|---|
005 | Classificado (data.pacote). No lote, o pedido foi aceito: confira o status de cada item em data.resultados. |
400 | Pedido fora do formato ou recusado pelo motor. Motivo na descricao, campo em data.campo. |
999 | Motor 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ódigo | Cenário |
|---|---|
005 | GET /certificado: situação e validade do certificado. |
001 | POST /certificado/a1: certificado instalado e já em uso. |
400 | Campo 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. |
999 | Falha 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ódigo | Cenário |
|---|---|
005 | Leitura (GET /rotinas...) e POST /rotinas/validar. |
001 | Gravaçã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. |
400 | Campo fora do formato (data.campo), regra do módulo, pendências que impedem ativar ou retomar (data.pendencias) ou chave sem permissão fiscal. |
500 | Rotina não encontrada nesta empresa. |
999 | Falha 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ódigo | Cenário |
|---|---|
001 | Pedido na fila (data.recibo). Com numero-origem já usado, é o recibo original (na fila ou já autorizado). |
400 | Recusado 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. |
999 | Falha interna ao registrar. Tente de novo. |
No GET /cte/{recibo} e GET /cte-os/{recibo}:
| Código | Cenário |
|---|---|
002 | Na fila, ainda não processado. Continue o polling. |
004 | Emissão autorizada (chave, protocolo, numero, serie, modelo, tp-amb, dh-recbto) ou evento registrado pela SEFAZ (tp-evento, protocolo). |
010 | O CT-e está cancelado (protocolo-cancelamento). |
900 | Recusado: 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. |
999 | Erro técnico ou desfecho indeterminado (data.erro). Reenvie o mesmo pedido. |
500 | Recibo 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ódigo | Cenário |
|---|---|
001 | Registrado na fila (ou, com o mesmo numero-origem, o recibo original). Comece o polling em GET /bpe/{recibo}. |
400 | Pedido 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. |
999 | Erro interno. Tente de novo. |
No GET /bpe/{recibo}:
| Código | Emissão / substituição | Eventos |
|---|---|---|
002 / 003 | Na fila / sendo emitido. Aguarde. | Na fila / sendo enviado. |
004 | Autorizado: chave, protocolo, qr-code. | Evento registrado (c-stat 135/136). |
010 | Autorizado e depois cancelado. | Cancelamento registrado. |
900 | Recusado 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). |
999 | Erro 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. |
500 | Recibo 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ódigo | data.situacao | Cenário | Ação |
|---|---|---|---|
002 | NA_FILA | Na fila. | Aguarde, consulte novamente. |
002 | AGUARDANDO_ASSINATURA_A3 | Montado; falta assinar com o certificado A3. | O operador assina no aplicativo assinador. Não reenvie. |
003 | PROCESSANDO | Sendo processado junto à SEFAZ. | Aguarde, consulte novamente. |
004 | AUTORIZADO | Autorizado. data.viagem: ABERTA ou ENCERRADA. Nos recibos de inclusão, data.evento. | Guarde chave e protocolo. Encerre ao fim da viagem. |
004 | ENCERRADO | Recibo do encerramento: manifesto encerrado. | — |
010 | CANCELADO | Cancelado (recibo do cancelamento, ou da emissão de manifesto cancelado depois). | Não reenvie. |
900 | REJEITADO | Recusado 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. |
999 | ERRO | Erro 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 abaixoconst 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';}