Rate Limits
Rate limits are enforced across the PRC API to prevent spam, abuse, and service disruptions caused by overloads.
The ER:LC API does not support bot hosting services, like Bot Ghost.
Services like BotGhost host many apps under the same IP, leading to frequent rate limits. It's best you do not use BotGhost when using the ER:LC API.
Definitions
On this page,
Application means an application (such as a Discord bot or website) with access to the PRC API. Each application is uniquly identified via their application key, provided in the Authorization header.
Server means a private server. Each server is uniquely identified with with the server key, provided via the Server-Key header.
Global Rate Limit
Each application is limited to a set number of requests per second - rate limits may vary per application and server! You should use the provided headers on each request to dynamically adjust your rate limits.
Rate Limits apply per-IP by default, large apps may have a global API key which allows for larger rate-limits and internal tracking.
Per-Route Rate Limit
Per-Route Rate Limits may be added to routes that are more intensive or subject to abuse. Rate Limits that differentiate from the global limit are identified via the X-RateLimit-Bucket header.
For example, the POST route to sen a command to an ER:LC server has a limit of 1 request per 5 seconds* (subject to change), this is identified via the X-RateLimit-Bucket header being set to command-[Server-Key].
Headers
For most standard API requests, we attach standard rate limit headers:
Please keep in mind the example values in this table are EXAMPLES - you should NOT hardcode rate limit data into your application!
X-RateLimit-Bucket
global
Which rate limit bucket the request was subject to
X-RateLimit-Limit
35
The number of requests that can be made to this bucket before a 429
X-RateLimit-Remaining
34
The number of remaining requests that can be made
X-RateLimit-Reset
*Epoch Timestamp*
Epoch timestamp when the rate limit resets
Being Rate Limited
When you exceed a rate limit, you will be met with a 429 HTTP Response code and a request body with a message, time to retry_after in seconds, and which bucket you have hit.
Normal rate limit headers (described above) will also be included.
Repeat Offender Rate Limits
Clients that continually send requests to the API after being sent 429s may be blocked for longer durations of time. It is very important that you respect the retry after headers and request body when you receive a HTTP 429 response.
Invalid Requests
Applications that send requests to invalid server-keys will be permanently blocked via IP if they continually send invalid requests over the period of several days.
As a best practice, if you receive a 403 error several times, stop using that server-key as it has likely been regenerated by the server's owner.
Last updated