---
updatedAt: 2026-09-01T13:50:42.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# Requisições bloqueadas por ausência de controle de limites

Esse erro ocorre quando a integração ultrapassa um limite da API e continua enviando requisições sem controlar a frequência, a concorrência ou as novas tentativas.

No Asaas, o erro `429 Too Many Requests` ocorre quando a integração ultrapassa o limite de um endpoint, a cota de 25 mil requisições em 12 horas ou o limite de 50 requisições GET concorrentes. Nos limites por frequência, os cabeçalhos `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset` indicam o total permitido, a quantidade restante e o tempo para liberação.

### Como identificar

* a API retorna `429 Too Many Requests`;
* a resposta informa limite de concorrência, cota excedida ou bloqueio temporário;
* o cabeçalho `RateLimit-Remaining` chegou a zero;
* o tempo indicado em `RateLimit-Reset` não é respeitado;
* muitas requisições GET são executadas simultaneamente;
* o erro ocorre após aumento repentino do volume;
* a integração realiza consultas repetidas ou polling em intervalos curtos;
* novas tentativas são executadas imediatamente após o erro.

### Como corrigir

1. Registre o código, o corpo, os cabeçalhos e o horário da resposta.
2. Identifique qual limite causou o erro.
3. Quando houver `RateLimit-Reset`, aguarde o período indicado.
4. Em caso de cota excedida, interrompa chamadas não essenciais e revise o volume consumido.
5. Em caso de concorrência elevada, limite as requisições simultâneas e utilize uma fila.
6. Interrompa retries imediatos após respostas `429`.
7. Aplique intervalos progressivos entre novas tentativas.
8. Remova consultas duplicadas ou desnecessárias.
9. Monitore volume, concorrência e ocorrência de bloqueios.

**Fluxo recomendado:** registrar a resposta → identificar o limite → aguardar a liberação → controlar o tráfego → tentar novamente → monitorar.

### Fluxo de diagnóstico

#### 1. Identificação do limite atingido

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 14,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["A API retornou<br/>erro 429"] --> B{"A resposta indica<br/>limite de concorrência?"}

B --> BSim(("Sim"))
B --> BNao(("Não"))

BSim --> C["Reduzir requisições<br/>GET simultâneas"]

BNao --> D{"Há indicação de reset<br/>ou cota excedida?"}

D --> DSim(("Sim"))
D --> DNao(("Não"))

DSim --> E["Aguardar a liberação<br/>e reduzir a frequência"]

DNao --> F["Registrar resposta, horário<br/>e volume das chamadas"]

C --> G["Limite identificado<br/>e ação aplicada"]
E --> G

F --> H["Coletar evidências<br/>para análise técnica"]

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

class A inicio
class B,D decisao
class C,E correcao
class G sucesso
class F,H analise

class BSim,DSim respostaSim
class BNao,DNao respostaNao

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 1,5 stroke:#22C55E,stroke-width:4px
linkStyle 2,6 stroke:#EF4444,stroke-width:4px
```

<br />

#### 2. Ajuste do consumo e dos retries

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["A causa do erro 429 foi identificada"] --> B{"Há controle de frequência e concorrência?"}

B --> BSim(("Sim"))
B --> BNao(("Não"))
B --> BDuvida(("Não sabe"))

BNao --> C["Implementar fila e limitar chamadas simultâneas"]

BDuvida --> D["Medir volume, concorrência e intervalos"]
D --> C

BSim --> E{"O sistema repete a chamada imediatamente?"}
C --> E

E --> ESim(("Sim"))
E --> ENao(("Não"))
E --> EDuvida(("Não sabe"))

ESim --> F["Respeitar o tempo de reset e aplicar espera progressiva"]
ENao --> G{"Há polling ou chamadas repetidas sem necessidade?"}

EDuvida --> H["Revisar logs e a política de retry"]
H --> F
F --> G

G --> GSim(("Sim"))
G --> GNao(("Não"))
G --> GDuvida(("Não sabe"))

GSim --> I["Reduzir polling e reutilizar dados já consultados"]
GNao --> J["Manter somente as chamadas necessárias"]

GDuvida --> K["Mapear a origem e a finalidade das chamadas"]
K --> L["Eliminar chamadas duplicadas ou desnecessárias"]

I --> M["Testar novamente com carga controlada"]
J --> M
L --> M

M --> N{"O erro 429 deixou de ocorrer?"}

N --> NSim(("Sim"))
N --> NNao(("Não"))

NSim --> O["Manter métricas, limites internos e alertas"]
NNao --> P["Recalibrar o controle e analisar o volume"]

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

class A inicio
class B,E,G,N decisao
class C,F,I,L correcao
class J,M validacao
class O sucesso
class D,H,K,P analise

class BSim,ESim,GSim,NSim respostaSim
class BNao,ENao,GNao,NNao respostaNao
class BDuvida,EDuvida,GDuvida respostaDuvida

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 1,9,17,28 stroke:#22C55E,stroke-width:4px
linkStyle 2,10,18,29 stroke:#EF4444,stroke-width:4px
linkStyle 3,11,19 stroke:#8B5CF6,stroke-width:4px
```

<br />

> O primeiro fluxo identifica **qual limite provocou o bloqueio**, enquanto o segundo orienta **como ajustar o consumo e impedir novos erros 429**.

<br />

### Como prevenir

Centralize as chamadas em uma fila, limite a concorrência e monitore os cabeçalhos de rate limit. Evite polling excessivo, reutilize dados já consultados e mantenha uma política de retry que respeite o tempo de liberação informado pela API.

Defina métricas e alertas para acompanhar volume, respostas `429`, chamadas simultâneas e consumo por operação.

> **O erro 429 não deve gerar um novo retry imediato. Identifique o limite, aguarde a liberação e controle o próximo envio.**

<br />

# Sibling pages

* [Webhook recebido, mas não persistido](https://docs.asaas.com/docs/webhook-recebido-mas-não-persistido.md)
* [Webhook com timeout ou resposta demorada](https://docs.asaas.com/docs/webhook-não-processado-dentro-do-tempo-esperado.md)
* [API Key usada no ambiente errado](https://docs.asaas.com/docs/api-key-de-sandbox-usada-em-produção.md)
* [Sistema dependente apenas da resposta síncrona](https://docs.asaas.com/docs/sistema-dependente-apenas-da-resposta-síncrona.md)
* [Cobrança duplicada após retry sem idempotência](https://docs.asaas.com/docs/cobrança-duplicada-após-retry-sem-idempotência.md)
* [Entidade criada sem vínculo com o registro interno](https://docs.asaas.com/docs/entidade-criada-sem-vínculo-com-o-registro-interno.md)
* [Status local divergente do Asaas](https://docs.asaas.com/docs/status-local-divergente-do-asaas.md)
* [Listagem incompleta por ausência de paginação](https://docs.asaas.com/docs/listagem-incompleta-por-ausência-de-paginação.md)
* [Webhook duplicado processado sem idempotência](https://docs.asaas.com/docs/webhook-duplicado-processado-sem-idempotência.md)