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

%%{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

2. Ajuste do consumo e dos retries

%%{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

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

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.