The API has three types of limits. When an applicable limit is exceeded, the request returns HTTP 429 Too Many Requests.
| Limit | Rule |
|---|---|
| Rate limit | Allowed frequency on certain endpoints |
| Quota | Up to 25,000 requests per account every 12 hours |
| Concurrency | Up to 50 simultaneous GET requests |
Rate limit
Certain endpoints have their own frequency limits.
Check the response headers to track usage:
RateLimit-Limit: 100
RateLimit-Remaining: 50
RateLimit-Reset: 30| Header | Description |
|---|---|
RateLimit-Limit | Number of requests allowed in the period |
RateLimit-Remaining | Number of remaining requests |
RateLimit-Reset | Seconds remaining until the limit is reset |
When RateLimit-Remaining reaches 0, new requests may return HTTP 429 Too Many Requests. Wait for the period indicated in RateLimit-Reset before trying again.
Quota limit
Each account can make up to 25,000 requests in a 12-hour period, regardless of the endpoints used.
The window starts with the first request. Calls made in the following 12 hours count toward this quota. After this period, the counter is reset.
When the limit is reached, the API returns HTTP 429 Too Many Requests.
Concurrent request limit
A request is considered concurrent when it is sent before a previous request has been answered.
The API allows up to 50 concurrent GET requests per account.
Calls that exceed this limit return HTTP 429 Too Many Requests.
How to handle the 429 error
Identify which limit was reached by the message in the response body. No header indicates the type of limit.
| Limit | Message in the response body | RateLimit-* headers | How to handle it |
|---|---|---|---|
| Concurrency | "Limite de requisições concorrentes atingido: N" | No | Reduce the number of simultaneous GET requests. |
| 12-hour quota | "Cota de requisições das últimas N horas excedida." | Yes | Reduce non-essential calls and wait for the quota to renew. |
| Endpoint rate limit | "Seu acesso foi temporariamente bloqueado..." | Yes | Wait for the period indicated in RateLimit-Reset. |
The quota and the endpoint rate limit return the same RateLimit-* headers. Use the message to tell them apart.
The Retry-After header is not sent in 429 responses. It is sent only when access is temporarily blocked with HTTP 403 Forbidden.
Do not retry immediately after a 429 response.
For diagnosis and traffic control strategies, see Requests blocked due to lack of limit control.
RecommendedDo not use recurring
GETqueries to track status changes when a corresponding Webhook exists.Use Webhooks to receive changes, and
GETqueries when you need to retrieve the current state of a resource.