Skip to main content
The ER:LC API enforces rate limits to ensure fair access and to protect infrastructure for all users. Understanding how these limits work, and how to respond to them correctly, is essential for building a reliable integration.

​
Definitions

Throughout this page, the following terms are used:
  • Application — an app (such as a Discord bot or website) that accesses the ER:LC API. Each application is uniquely identified by its global API key, provided in the Authorization header.
  • Server — a private server identified by its server-key, provided via the Server-Key header.

​
Global rate limit

By default, rate limits are applied per IP address. Each application is limited to a set number of requests per second, and this limit can vary per application and per server.
Always use the rate limit headers returned on each response to dynamically adjust your request rate. Don’t hardcode rate limit values — they can change and vary by application.
Large-scale applications may be issued a global API key, which increases allowed request volume and provides higher per-IP limits. See Global API Keys for Large-Scale Applications for details.

​
Per-route rate limit

Some routes have tighter limits than the global rate limit because they are more resource-intensive or more prone to abuse. These routes are identified by the X-RateLimit-Bucket response header containing a value other than global. For example, the POST /command route has a limit of 1 request per 5 seconds (subject to change). This is indicated by X-RateLimit-Bucket being set to command-[Server-Key].

​
Rate limit headers

The API attaches the following headers to most standard responses:

​
What to do when you receive a HTTP 429 response

When you exceed a limit, the API returns HTTP 429 with a Retry-After header (in seconds) and a JSON body containing retry_after. In order to prevent longer API bans, you must stop sending requests immediately and wait the full Retry-After duration before sending any new requests.

​
Invalid request blocks

If your application continues sending requests after receiving 429 responses, instead of waiting as instructed by Retry-After, it may be placed under an invalid request block. Invalid Request blocks typically last several hours. While blocked, every request returns a 429 with a message identifying the block and when it lifts.
Applications that persistently fail to respect rate limits will be automatically blocked via Cloudflare. If you encounter a Cloudflare block page, you must contact us by opening an API ticket in the ER:LC Discord server.

​
Invalid server-key requests

Sending repeated requests to invalid server-keys will result in an IP ban. If a server owner regenerates their server-key, your old key will return 403 responses.
Best practice: If you receive a 403 error several times for the same server-key, stop using that key. It has likely been regenerated by the server owner. Remove it from your system to avoid an IP ban.

​
Services with shared IPs (including BotGhost) are not supported

The ER:LC API does not support BotGhost or similar shared-hosting services that run many applications under the same IP address, which may causes frequent rate limit collisions that cannot be resolved. For reliable API access, host your application on a dedicated IP.