Erros e códigos de retorno comuns em APIs de notas fiscais
· 6 min de leitura
Erros ao consultar uma API de notas fiscais costumam cair em três categorias, seguindo convenções padrão de HTTP: falha de autenticação, parâmetro inválido na chamada, ou indisponibilidade temporária do serviço, cada uma pede um tratamento diferente de quem integra.
Erros de autenticação
Costumam aparecer como recusa de conexão ou erro no nível de autenticação (categorias 401 e 403 em APIs REST convencionais), em geral por certificado vencido, inválido ou do CNPJ errado. Não costumam se resolver sozinhos com uma nova tentativa: exigem checar o certificado usado antes de tentar de novo.
Erros de parâmetro
Acontecem quando a chamada está malformada: um NSU inválido, um CNPJ em formato errado, um campo obrigatório faltando (categoria 400 em APIs REST convencionais). Costumam ser fáceis de corrigir: revisar o payload enviado contra o schema documentado geralmente resolve.
Indisponibilidade temporária
Diferente dos dois anteriores, uma indisponibilidade (timeout, erro de servidor) costuma ser passageira: a resposta correta é tentar de novo depois de um intervalo, não assumir que há algo errado com a consulta em si. Uma integração bem-feita trata esse caso com reprocessamento automático, não com falha silenciosa.
Perguntas frequentes
Um erro de indisponibilidade significa que a nota não existe?
Não, indisponibilidade é um problema temporário de acesso ao serviço, sem relação com a existência ou não do documento fiscal. A forma de confirmar se a nota existe é repetir a consulta depois que o serviço voltar a responder normalmente.
Como validar se os dados retornados (quando a chamada dá certo) estão corretos?
Isso é uma etapa separada da consulta em si: veja como validar os dados recebidos por uma API de NFS-e.
Tratar cada uma dessas categorias de erro corretamente (sem confundir indisponibilidade com ausência de nota, por exemplo) é justamente o tipo de detalhe que uma integração própria precisa acertar. A IntegroBR NFS-e Recebidas já trata esses casos por trás, incluindo reprocessamento automático de falhas temporárias.