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 automática (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). Endpoints /maintenance/* exigem role Management.
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.

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 automática (deactivationReason)

Quando uma empresa é desativada pelo circuit breaker, 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
CertificateNotFound	Certificado removido após ativação	Faça upload do A1 no painel.
CertificateExpired	Certificado A1 fora da validade	Renove no painel e reative.
CertificateRejected	SEFIN rejeitou o certificado	Confirme se o certificado bate com o CNPJ da empresa; renove se necessário.
CompanyNotAuthorized	CNPJ não autorizado no padrão nacional NFS-e	Verifique o cadastro da empresa no Ambiente Nacional.

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

Os mecanismos abaixo regem o comportamento do polling e podem disparar a desativação, mas não aparecem no campo deactivationReason — o campo só assume um dos 4 valores acima.

• Circuit breaker — após 10 falhas consecutivas de autenticação no poll do ADN o circuito abre; quando a causa é certificado, a desativação é registrada com o deactivationReason correspondente (ex.: CertificateRejected). Verifique o status do SEFIN em gov.br/nfse e os logs da empresa.
• Rate limit — quando o ADN retorna 429, o campo rateLimitedUntil é preenchido e o poll é pausado até o cooldown; a captura retoma sozinha. Isto não desativa a empresa nem grava deactivationReason.
• Desativação manual — DELETE /companies/{companyId}/inbound/nfse/details (ou PUT /details com isActive: false) desativa a empresa por ação do operador, sem gravar deactivationReason. Reative com /maintenance/reactivate ou PUT /details com isActive: true.

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.

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.
• 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.
• 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