---
title: "Troubleshooting — NFe / CTe Inbound"
description: "Sinais de problema na recepção de NF-e/CT-e e como diagnosticar: NSU travado, empresa desativada, webhooks não chegando, rate limit."
source_url: https://nfe.io/docs/distribuicao-nfe-cte-troubleshooting/
last_updated: 2026-07-30
---

# Troubleshooting — NFe / CTe Inbound

## Sinais de problema (e o que verificar)

| Sintoma | Causa provável | O que fazer |
|---|---|---|
| **Último NSU não avança** | Sem documentos novos, ou captura pausada | Confirme se há documentos no período; verifique o status da empresa |
| **Status Inativo (vermelho)** | Desativação automática (circuit breaker) — ex.: certificado | Corrija a causa e reative; veja [Certificado digital](../explanation/certificado-digital.md) |
| **Webhooks não chegam** | URL inacessível, retornando ≠2xx, ou validação HMAC falhando | Teste a URL; valide a assinatura `x-hub-signature`; use o reprocessamento |
| **`rateLimitedUntil` preenchido** | Limite de taxa atingido no ambiente nacional | Aguarde a data informada; reduza a frequência de chamadas |

## Reenviar um webhook

Após esgotar as tentativas automáticas, o documento continua consultável. Reenvie manualmente:

```bash
curl -X POST "https://api.nfe.io/v2/companies/{company_id}/inbound/productinvoices/{access_key}/processwebhook" \
  -H "Authorization: SUA_API_KEY"
```

## Erros de autenticação

- `401` — chave ausente/inválida. Envie a API Key no header `Authorization` **sem prefixo** (veja [Autenticação](../../comum/autenticacao.md)).
- `403` — chave sem o papel necessário (`Nota Fiscal (api.nfe.io)`, ou `NFeDist`/`CTeDist (dfe.nfe.io)`).

## Checklist de diagnóstico

- [ ] Empresa **ativa** para o tipo de documento?
- [ ] Certificado A1 válido (NF-e/CT-e)?
- [ ] Período consultado tem documentos? (SEFAZ guarda ~90 dias)
- [ ] Webhook respondendo `2xx` em <5s e validando HMAC?
- [ ] API Key com o papel correto e sem prefixo no header?

## Veja também

- [Erros HTTP](./http-errors.md) · [Webhook — eventos e HMAC](./webhook-events.md)
- [Conceitos](../explanation/conceitos.md)