---
title: "Troubleshooting — NFS-e Inbound"
description: "Catálogo de códigos HTTP, cStat SEFIN, deactivationReason e sintomas operacionais comuns do NFS-e Inbound — com causa e ação recomendada para cada um."
source_url: https://nfe.io/docs/distribuicao-nfse-inbound-troubleshooting/
last_updated: 2026-07-30
---

# 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](../explanation/arquitetura.md).

## Sumário

- [Como usar este catálogo](#como-usar-este-catálogo)
- [Códigos HTTP da API](#códigos-http-da-api)
- [Códigos `cStat` do SEFIN (manifestação)](#códigos-cstat-do-sefin-manifestação)
- [Razões de desativação automática (`deactivationReason`)](#razões-de-desativação-automática-deactivationreason)
- [Status de processamento e webhook](#status-de-processamento-e-webhook)
- [Sintomas operacionais comuns](#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](../how-to/manifestacao-tomador.md).
- **`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`.

:::info 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](codigos-evento.md) 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](../how-to/integracao-rest.md). |
| `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](https://www.gov.br/nfse/).

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

:::note 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](https://www.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](webhook-events.md#idempotência).
- **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](../how-to/bulk-export.md).

## Veja também

- [Arquitetura do NFS-e Inbound](../explanation/arquitetura.md) — fluxo completo SEFIN → ADN → NFE.io → cliente
- [Integração via REST](../how-to/integracao-rest.md) — guia de integração com tratamento de erros básico
- [Catálogo de eventos do webhook](webhook-events.md) — `webhookStatus`, retry policy, idempotência
- [Códigos de evento](codigos-evento.md) — XSD `tpEvento` vs CSV `EventCode`
- [Receita — Manifestação](../how-to/manifestacao-tomador.md) — onde os `cStat` SEFIN aparecem
- [Receita — Bulk Export](../how-to/bulk-export.md) — diagnóstico de jobs `Failed`