The Top.gg API enforces rate limits to protect platform stability and prevent abuse. When you exceed a limit, the API returns an HTTP 429 response and blocks your token for one hour. Understanding the limits before you integrate helps you avoid interruptions.
Global rate limit
The global rate limit applies to all API routes regardless of the resource being accessed.
| Scope | Limit | Penalty |
|---|
| All routes | 100 requests per second | 1-hour token block |
Resource-specific rate limits
Certain routes have stricter limits in addition to the global limit. Both limits apply simultaneously.
| Route | Limit | Penalty |
|---|
/bots/* | 60 requests per minute | 1-hour token block |
/bots/* endpoint, your token is blocked for one hour even if you are within the global limit.
Handling rate limit errors
When you exceed a rate limit, the API responds with HTTP 429 and a JSON body containing the number of seconds to wait before retrying:
Read the retry-after value and pause all requests for that duration before retrying. Retrying immediately will not succeed and may extend the block.
Repeatedly exceeding rate limits can result in a permanent platform ban. Implement proper backoff logic and respect the retry-after value in every 429 response.
Community SDKs for Top.gg (available for Node.js, Python, and other languages) handle rate limiting and retry logic automatically. Using an SDK reduces the risk of accidentally triggering blocks.
