Requests blocked due to missing rate limit control

This error occurs when the integration exceeds an API limit and keeps sending requests without controlling frequency, concurrency, or retries.

In Asaas, the 429 Too Many Requests error occurs when the integration exceeds an endpoint's limit, the quota of 25 thousand requests in 12 hours, or the limit of 50 concurrent GET requests. For frequency-based limits, the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers indicate the total allowed, the remaining amount, and the time until the limit resets.

How to identify

• the API returns 429 Too Many Requests;
• the response reports a concurrency limit, exceeded quota, or temporary block;
• the RateLimit-Remaining header has reached zero;
• the time indicated in RateLimit-Reset is not respected;
• many GET requests are executed simultaneously;
• the error occurs after a sudden increase in volume;
• the integration performs repeated queries or polling at short intervals;
• retries are executed immediately after the error.

How to fix

1. Record the response code, body, headers, and time.
2. Identify which limit caused the error.
3. When RateLimit-Reset is present, wait for the indicated period.
4. If the quota was exceeded, stop non-essential calls and review the volume consumed.
5. If concurrency is high, limit simultaneous requests and use a queue.
6. Stop immediate retries after 429 responses.
7. Apply progressive intervals between retries.
8. Remove duplicate or unnecessary queries.
9. Monitor volume, concurrency, and the occurrence of blocks.

Recommended flow: record the response → identify the limit → wait for the reset → control traffic → try again → monitor.

Diagnostic flow

1. Identifying the limit reached

%%{init: {"flowchart": {"nodeSpacing": 14,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["The API returned<br/>a 429 error"] --> B{"Does the response indicate<br/>a concurrency limit?"}

B --> BSim(("Yes"))
B --> BNao(("No"))

BSim --> C["Reduce simultaneous<br/>GET requests"]

BNao --> D{"Is there a reset indication<br/>or exceeded quota?"}

D --> DSim(("Yes"))
D --> DNao(("No"))

DSim --> E["Wait for the reset<br/>and reduce frequency"]

DNao --> F["Record response, time,<br/>and call volume"]

C --> G["Limit identified<br/>and action applied"]
E --> G

F --> H["Collect evidence<br/>for technical analysis"]

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. Adjusting consumption and retries

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["The cause of the 429 error was identified"] --> B{"Is there frequency and concurrency control?"}

B --> BSim(("Yes"))
B --> BNao(("No"))
B --> BDuvida(("Not sure"))

BNao --> C["Implement a queue and limit simultaneous calls"]

BDuvida --> D["Measure volume, concurrency, and intervals"]
D --> C

BSim --> E{"Does the system repeat the call immediately?"}
C --> E

E --> ESim(("Yes"))
E --> ENao(("No"))
E --> EDuvida(("Not sure"))

ESim --> F["Respect the reset time and apply progressive backoff"]
ENao --> G{"Is there unnecessary polling or repeated calls?"}

EDuvida --> H["Review logs and the retry policy"]
H --> F
F --> G

G --> GSim(("Yes"))
G --> GNao(("No"))
G --> GDuvida(("Not sure"))

GSim --> I["Reduce polling and reuse already retrieved data"]
GNao --> J["Keep only the necessary calls"]

GDuvida --> K["Map the origin and purpose of the calls"]
K --> L["Eliminate duplicate or unnecessary calls"]

I --> M["Test again with controlled load"]
J --> M
L --> M

M --> N{"Has the 429 error stopped occurring?"}

N --> NSim(("Yes"))
N --> NNao(("No"))

NSim --> O["Maintain metrics, internal limits, and alerts"]
NNao --> P["Recalibrate the control and analyze the 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

The first flow identifies which limit caused the block, while the second explains how to adjust consumption and prevent new 429 errors.

How to prevent

Centralize calls in a queue, limit concurrency, and monitor the rate limit headers. Avoid excessive polling, reuse data you have already retrieved, and maintain a retry policy that respects the reset time reported by the API.

Define metrics and alerts to track volume, 429 responses, simultaneous calls, and consumption per operation.

A 429 error should not trigger an immediate new retry. Identify the limit, wait for the reset, and control the next request.