SEFAZ lenta ou instável

A emissão de documentos fiscais pela API é assíncrona: o POST de emissão devolve um recibo, e o resultado deve ser acompanhado pela consulta (GET .../{recibo}). Na operação normal, a SEFAZ autoriza em poucos segundos.

Em alguns momentos (instabilidade ou lentidão da SEFAZ), a autorização pode levar mais de 15 segundos. Nessa janela, a consulta do recibo pode devolver temporariamente:

{
  "status": "900",
  "descricao": "A SEFAZ recusou a nota.",
  "data": {
    "sefaz": {
      "codigo": "217",
      "mensagem": "Rejeição: NF-e não consta na base de dados da SEFAZ"
    }
  }
}

O código 900 NÃO é sempre uma rejeição definitiva

Nesse contexto específico, o status: "900" acompanhado de sefaz.codigo 217 (ou 105) não é uma rejeição definitiva — é apenas o retrato de um instante em que a SEFAZ ainda não terminou de processar a nota. A autorização pode ser concluída segundos ou minutos depois desse retorno, e nosso sistema corrige automaticamente o status assim que isso acontecer (veja abaixo). Trate 900 como terminal apenas quando sefaz.codigo não estiver nessa lista de códigos transitórios — veja a regra de ouro a seguir.

A regra de ouro: decida pelo sefaz.codigo, nunca pelo status sozinho

sefaz.codigo	Significado	Ação do integrador
100 (ou 150)	Autorizada (protocolo e XML disponíveis)	Concluir a venda / imprimir DANFE
217 ou 105	Transitório — SEFAZ ainda processando	Aguardar e seguir consultando o mesmo recibo — não reemitir
ausente / vazio	Nota na fila ou enviada, sem retorno ainda (status 002/003)	Aguardar e seguir consultando o mesmo recibo
Qualquer outro (ex.: 204, 539, 770…)	Rejeição definitiva	Corrigir o dado apontado em sefaz.mensagem e emitir novamente

O que o nosso sistema faz automaticamente

Você não precisa (e não deve) reenviar a nota. Nosso sistema possui reconciliação automática: um processo interno re-consulta a situação da nota diretamente na SEFAZ (pela chave de acesso) e atualiza o resultado assim que houver resposta definitiva:

• Se a SEFAZ autorizou → a consulta do recibo passa a devolver status: "004", com protocolo de autorização e XML definitivo — como em qualquer emissão normal.
• Se a SEFAZ rejeitou de fato → sefaz.codigo/sefaz.mensagem passam a refletir a rejeição real, para correção e reenvio.

Na maioria dos casos a situação se resolve em poucos minutos. A janela de reconciliação automática cobre até 3 horas.

Ação necessária do integrador

1. Continue consultando o mesmo recibo até obter um resultado definitivo (sefaz.codigo = 100 ou um código de rejeição real). Sugestão de polling: a cada 2–5 s no primeiro minuto; depois a cada 30–60 s.
2. Nunca reenvie a mesma venda enquanto sefaz.codigo for 217, 105 ou estiver ausente. A nota pode já ter sido autorizada na SEFAZ — reenviar gera duplicidade de documento fiscal (duas notas válidas para a mesma venda).
3. Só considere a venda concluída (impressão de DANFE, baixa no seu sistema) quando sefaz.codigo = 100.
4. Se receber uma rejeição definitiva (código ≠ 100/217/105, ex.: erro cadastral ou tributário), corrija o dado apontado em sefaz.mensagem e aí sim emita novamente.
5. Se uma nota permanecer com sefaz.codigo = 217 (ou 105) por mais de 3 horas, não reemita por conta própria — acione o suporte informando o recibo e a chave de acesso, para verificação manual.

Resumo por situação

Situação	status	sefaz.codigo	Ação
Autorizada	004	100	Concluir a venda / imprimir DANFE
SEFAZ lenta (transitório)	900 ⚠️	217 (ou 105)	Aguardar e repetir a consulta — não reemitir
Em fila / sem retorno ainda	002 / 003	ausente	Aguardar e repetir a consulta
Rejeição definitiva	900	≠ 100/217/105	Corrigir o dado e emitir novamente
Cancelada	010	—	—
Transitório por mais de 3h	900	217 (ou 105)	Contatar o suporte com recibo + chave — não reemitir

Checando isso no código do seu cliente

O padrão de classificação de status descrito em Códigos de status precisa de um ajuste para este cenário: 900 não deve ser tratado como terminal incondicionalmente — primeiro verifique data.sefaz.codigo:

const SEFAZ_TRANSITORIO = ['217', '105'];

function classificarComSefaz(json: { status: string; data?: { sefaz?: { codigo?: string } } }) {
  const codigoSefaz = json.data?.sefaz?.codigo;

  // status 900 com codigo transitorio => AINDA NAO é definitivo, continue consultando
  if (json.status === '900' && codigoSefaz && SEFAZ_TRANSITORIO.includes(codigoSefaz)) {
    return 'pendente';
  }

  if (['004', '010'].includes(json.status)) return 'sucesso';
  if (['500', '900', '999'].includes(json.status)) return 'falha';
  if (['001', '002', '003'].includes(json.status)) return 'pendente';
  return 'falha';
}

Veja também Fluxo assíncrono para o exemplo completo de polling com backoff.