Troubleshooting — NFS-e Inbound

Catálogo de códigos e sintomas operacionais do NFS-e Inbound, agrupados por família. Use a primeira coluna como pivô para diagnóstico rápido. Para visão sistêmica do fluxo, leia Arquitetura.

Sumário

• Como usar este catálogo
• Códigos HTTP da API
• Códigos cStat do SEFIN (manifestação)
• Razões de desativação (deactivationReason)
• Status de processamento e webhook
• Sintomas operacionais comuns

Como usar este catálogo

• Códigos HTTP aparecem na resposta de qualquer chamada à API REST (POST /v2/..., GET /v2/...).
• cStat do SEFIN aparece no campo errorCode de uma manifestação com status: Rejected ou Failed — veja Receita — Manifestação.
• deactivationReason aparece no campo da empresa quando isActive: false — também no payload do webhook inbound.company.deactivated.
• status e webhookStatus aparecem em cada documento ao listar GET /v2/companies/{companyId}/inbound/nfse.

Códigos numéricos de evento têm dois contextos

Não confunda eventCode do XSD tpEvento (101101, 105102, 203202, 203206, 205204, 305101 — aparecem no webhook e em manifestações) com EventCode do CSV (310610 cancelamento, 310611 substituição — aparecem apenas no bulk export analítico). Veja Códigos de evento para a tabela canônica.

Para cada código, a coluna Ação recomendada traz o caminho concreto de remediação. Quando a ação envolve um endpoint, ele é referenciado em backticks.

Códigos HTTP da API

Código	Mensagem típica	Causa	Ação recomendada
401	Unauthorized	API Key ausente, inválida ou inativa	Verifique header Authorization; gere nova chave no painel com descrição "Nota Fiscal (api.nfe.io)" e status Ativa.
403	Forbidden	API Key sem o papel exigido (Nota Fiscal/NFSeDist ou role Management)	Use uma chave com papel Nota Fiscal (api.nfe.io) ou NFSeDist (dfe.nfe.io). Os endpoints de manutenção notifications/statistics/reactivate exigem role Management; o fetch-now também aceita NFSeDist (própria empresa).
404	CompanyNotFound, Documento não encontrado	Recurso não existe, pertence a outra conta, ou accessKey/id errado	Confirme o companyId e revise o accessKey (50 dígitos) ou id (24 hex chars).
404	CertificateUnavailable	Empresa sem certificado registrado	Cadastre o certificado A1 no painel antes de ativar o Inbound.
409	Conflict	Recurso duplicado: companyId já cadastrado, ou manifestação Pending em flight para (accessKey, eventCode)	Consulte GET /companies/{companyId}/inbound/nfse/details ou GET /manifestations antes de re-enviar.
422	Unprocessable Entity	Regra de negócio violada: eventCode=203206 sem reasonCode, NSU regressivo, etc.	Revise o body conforme Integração REST.
502	CertificateRejected	Certificado da empresa rejeitado pelo SEFIN (CN não bate, vencido)	Renove o certificado e reative com POST /maintenance/reactivate.
503	AdnUnavailable	SEFIN Nacional indisponível (inclui header Retry-After)	Aguarde o intervalo do header e retente. Captura automática retoma sozinha.
503	CertificateLookupFailed	Falhou a consulta ao certificado — não se sabe se existe	Retente. Não cadastre um certificado novo por conta disso: pode já haver um válido.
403	AccessForbidden	Sigilo fiscal na captura sob demanda: o certificado da empresa não é Prestador, Tomador nem Intermediário da nota	Confirme se a chave é de uma nota da sua empresa. Não há contorno.

Códigos cStat do SEFIN (manifestação)

Aparecem em errorCode quando uma manifestação termina em Rejected ou Failed. errorMessage traz o xMotivo literal da resposta SEFIN.

cStat	Significado	Causa	Ação recomendada
135	Evento registrado e vinculado à NFS-e	Sucesso completo	Nenhuma — status virou Accepted.
136	Evento registrado, não vinculado	Chave de acesso provavelmente incorreta	Confirme o accessKey (50 dígitos) antes de re-submeter. Não re-envie sem investigar.
217	NFS-e não consta na base SEFIN	Latência ADN entre publicação e indexação para eventos	Aguarde 2-10 minutos e re-submeta.
573	Duplicidade de evento	Já existe evento do mesmo tipo para (accessKey, eventCode)	GET /by-access-key/{accessKey}/manifestations para confirmar; provavelmente já está OK.
999	Erro interno SEFIN	Indisponibilidade temporária da SEFIN Nacional	Retentar após 5-10 minutos. Se persistir, abra chamado no suporte.

Outros cStat documentados pelo SEFIN são propagados sem tradução — consulte o Manual de Orientação ao Contribuinte NFS-e Nacional.

Razões de desativação (deactivationReason)

Quando uma empresa é desativada, o webhook inbound.company.deactivated é enviado e isActive vira false. Recuperação sempre via POST /v2/companies/{companyId}/inbound/nfse/maintenance/reactivate após sanar a causa.

deactivationReason	Causa	Ação recomendada
CertificateRejected	SEFIN rejeitou o certificado em falhas consecutivas até atingir o limite do circuit breaker	Confirme se o certificado bate com o CNPJ da empresa; renove se necessário e reative.
ManualDeactivation	Desativação por ação do operador ou do cliente (DELETE .../details, ou PUT .../details com isActive: false)	Reative com /maintenance/reactivate ou PUT .../details com isActive: true.

Valores legados, que aparecem apenas em empresas desativadas no passado (nenhum fluxo atual os grava): CertificateNotFound, CertificateExpired, CompanyNotAuthorized.

Certificado indisponível não desativa mais a empresa — apenas espaça a captura

Certificado não cadastrado, fora da validade ou em custódia não suportada (ex.: chave em HSM, que não permite o mTLS exigido pelo ADN) faz a empresa permanecer ativa: o poll aplica um cooldown, preenchendo rateLimitedUntil, e volta a tentar depois. Assim a captura retoma sozinha quando o certificado é regularizado, sem depender de reativação manual — e sem perder documentos, já que o cursor de NSU não avança.

Como esse caso se apresenta: isActive: true, deactivationReason: null, rateLimitedUntil no futuro e currentNsu parado. Ação: regularizar o certificado da empresa.

Condições operacionais (não são valores de deactivationReason)

• Circuit breaker — após 10 falhas consecutivas de autenticação no poll do ADN o circuito abre; quando a causa é rejeição do certificado pela SEFIN, a desativação é registrada como CertificateRejected. Verifique o status do SEFIN em gov.br/nfse e os logs da empresa.
• rateLimitedUntil — o campo tem duas causas distintas e o valor em si não diz qual foi: (1) o ADN retornou 429 (rate limit) ou (2) o certificado da empresa está indisponível/inutilizável (bloco acima). Em ambos os casos o poll é pausado até o cooldown e retoma sozinho, e em nenhum deles a empresa é desativada. Para distinguir, verifique o certificado: se estiver válido e registrado, é rate limit.

Status de processamento e webhook

Campo	Valor	Significado	Ação
status	Received	Aguardando processamento	Aguarde; transita para Processed em segundos.
status	Processed	XML persistido e webhook entregue	Nenhuma — fluxo normal.
status	Failed	Falha irrecuperável (XML corrompido)	POST .../{id}/reprocess para tentar de novo. Se persistir, abra suporte.
status	PdfPending	XML OK, PDF em geração	Aguardar; consulta GET .../{id}/pdf retorna 202 enquanto pendente.
status	PdfFailed	Geração de PDF falhou (XML pode ser incompatível)	POST .../{id}/reprocess.
webhookStatus	Delivered	Cliente respondeu 2xx	Nenhuma.
webhookStatus	Retrying	Em backoff (até 50x em 24h)	Verifique seu endpoint; ajuste timeout se >30s.
webhookStatus	DefinitivelyFailed	Esgotou todas as tentativas	POST .../{id}/resend-webhook após corrigir o endpoint.
webhookStatus	Skipped	Não haverá entrega: o documento é anterior à data de corte da empresa (histórico retido). Não é falha	Nada a corrigir no seu endpoint. Se você precisa desses documentos, a liberação do histórico é contratada à parte — veja Manutenção administrativa.

Sintomas operacionais comuns

• Não recebo nenhum documento depois de ativar. Verifique se há prestadores emitindo NFS-e contra o seu CNPJ no padrão nacional, e confirme que a empresa está ativa (isActive: true) com certificado válido.
• currentNsu não avança. Verifique lastExecutedAt em GET /maintenance/statistics. Se atrasado, provavelmente há rateLimitedUntil ativo ou deactivationReason preenchido — confira isActive. Com isActive: true e rateLimitedUntil no futuro, a causa mais comum é certificado indisponível ou vencido (ver acima), não rate limit.
• Webhook chega múltiplas vezes para o mesmo documento. Comportamento esperado (entrega at-least-once). Implemente idempotência por (companyId, nsu) ou document.id — veja Catálogo do webhook.
• 404 em um documento que existe (você tem a chave, ou ele aparecia antes). Documentos anteriores à data de corte da empresa ficam retidos enquanto o histórico não é liberado, e todas as portas de leitura os tratam como inexistentes — listagem, detalhe, XML/PDF/JSON, reenvio de webhook, reprocesso, captura sob demanda e manifestação por chave. Consulte GET .../inbound/nfse/backfill: hiddenDocumentsCount conta os retidos e released diz se já foram liberados.
• PDF do documento retorna 404 ao baixar. Confirme hasPdf: true no detalhe do documento. Para type=Event/Dps/Cnc, o PDF nunca existe (pdfUrl: null é esperado).
• URL assinada (xmlUrl/pdfUrl) retornou 400 "Link expired." O link HMAC expira em 30 minutos. Refaça o GET /{id}/xml ou /pdf para obter nova URL. Não cacheie links assinados.
• Job de bulk export "Em processamento" há mais de 1 hora. Pode estar travado. Confirme via GET .../exports({jobId}) se progredindo; se não, contate o suporte com o jobId. Veja Receita — Bulk Export.

Veja também

• Arquitetura do NFS-e Inbound — fluxo completo SEFIN → ADN → NFE.io → cliente
• Integração via REST — guia de integração com tratamento de erros básico
• Catálogo de eventos do webhook — webhookStatus, retry policy, idempotência
• Códigos de evento — XSD tpEvento vs CSV EventCode
• Receita — Manifestação — onde os cStat SEFIN aparecem
• Receita — Bulk Export — diagnóstico de jobs Failed