Emissor fiscal que só diz "erro" é o que faz a nota ficar parada no fim do dia. A API separa três coisas: a chamada errada (cabeçalho, chave), o campo errado (antes de ir à Sefaz) e a recusa da própria Sefaz. Cada uma tem um código e um jeito de resolver.
A tabela completa
| HTTP | Quando | O que fazer |
|---|---|---|
| 201 | Nota autorizada | Guardar id e chave. |
| 200 | Repetição da mesma chave e corpo | Nada: é a mesma nota. |
| 202 | Pendente: a Sefaz não respondeu | Não reenviar com chave nova; sincronizar depois de 1 minuto. |
| 400 | Sem Idempotency-Key ou JSON malformado | Corrigir a chamada. |
| 401 | Sem chave, chave desconhecida ou revogada | Conferir a chave de API. |
| 402 | Assinatura em atraso | Regularizar. Consultar e baixar continuam funcionando. |
| 403 | Chave sem permissão para o tipo de nota | Marcar NF-e ou NFS-e na chave, no painel. |
| 409 | Chave já usada com outro corpo, ou em processamento | Outra venda = outra chave; ou consultar em instantes. |
| 422 | Campo inválido ou recusa da Sefaz | Corrigir e reenviar (pode ser a mesma chave). |
| 429 | Sincronizar antes de 1 minuto | Esperar. |
| 503 | Emissor fiscal indisponível no servidor | Tentar mais tarde com a mesma chave. |
Campo inválido: o erro diz onde
Antes de ir à Sefaz, a nota é conferida. Se algo não fecha, nada é enviado e a resposta aponta cada problema com o caminho do campo:
HTTP/1.1 422
{
"mensagem": "A nota tem campos inválidos — nada foi enviado à SEFAZ.",
"erros": [
"itens[0].ncm: 8 dígitos.",
"pagamentos: a soma (90,00) não fecha com o total da nota (95,00)."
]
}Recusa da Sefaz: o motivo vem inteiro
Quando a validação passa mas a Sefaz recusa, o corpo traz a nota com a situação rejeitada e o motivo original em nota.mensagem, com o código da Sefaz entre colchetes. Não há tradução que esconda o problema: o texto é o da Sefaz, que é o que o contador e o suporte reconhecem.
Os tropeços mais comuns
- Código do município com menos de 7 dígitos. É o código do IBGE, não o CEP.
- CFOP de dentro do estado (5xxx) numa venda para outro estado (6xxx), ou o contrário.
- Regime errado: empresa do Simples mandando CST, ou regime normal mandando CSOSN.
- Pagamentos que não somam o total da nota (lembre do frete e do desconto).
- NCM desatualizado: a tabela muda, e o código antigo passa a ser recusado.
Conhecer a API de nota fiscal Documentação completa
Tutorial escrito pela equipe da API em 29 de setembro de 2026, conferido com a versão v1 no ar. Regra fiscal muda: o enquadramento de imposto da sua empresa é com o seu contador. Viu algo desatualizado? Fale com a gente pelo WhatsApp.