Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.erlc.gg/llms.txt

Use this file to discover all available pages before exploring further.

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:
HeaderExample ValueDescription
X-RateLimit-BucketglobalWhich rate limit bucket the request was subject to
X-RateLimit-Limit35The total number of requests allowed in this bucket before a 429
X-RateLimit-Remaining34The number of requests remaining in the current window
X-RateLimit-Reset*Epoch Timestamp*Epoch timestamp when the current rate limit window resets

​
Handling a 429 response

When you exceed a rate limit, the API returns an HTTP 429 status code. The response body includes:
  • A human-readable message
  • retry_after — the number of seconds to wait before retrying
  • The name of the bucket that was exceeded
Normal rate limit headers are also included in the 429 response. You must respect the retry_after value and pause requests until the window resets.

​
Repeat offenders

Applications that continue sending requests after receiving 429 responses may be blocked for increasingly longer durations.
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 to resolve the block.

​
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.