Rate limits¶

TEBHOS bounds HTTP API traffic with per-operation buckets and one global bucket. A bucket is an allowance of requests over a window. A request over the allowance is refused with 429, code set to RATE_LIMITED, a rate limit response object and the rate limit headers.

How buckets work¶

Every bucket is a leaky bucket. It admits at most its limit at once and then drains continuously at limit requests per window. A client that exhausts an allowance can send again as soon as enough of it has drained; it does not have to wait for the whole window.

For example, channel:message:create has a limit of 20 per 10 seconds. A client can send 20 messages in a burst, after which one more message is admitted roughly every 0.5 seconds.

Buckets and keys¶

Most operations check a named bucket. The bucket name itself is not sent to clients; X-RateLimit-Bucket carries a stable 16-character hexadecimal hash of it, so a client can tell which operations share an allowance.

Each bucket is keyed by an identity, so separate callers have separate allowances. The key depends on the operation and is listed in the bucket tables:

A bot and its owner are different accounts and never share an allowance.

Some operations check more than one bucket, for example login (per IP and per submitted login name) and group DM creation (the DM bucket plus an hourly group bucket). The request must pass every bucket.

Global limit¶

Every request below /api/v1 also counts against a global bucket of 50 requests per second per client. The client is identified by its Authorization header, or by its IP address when it sends none.

These requests do not count against the global bucket:

• CORS preflight (OPTIONS) requests.
• GET and HEAD requests for public media such as avatars, icons and attachments.
• GET and HEAD requests sent without an Authorization header.
• Webhook execution (POST /webhooks/{webhook_id}/{token} and its integration variants) and webhook message read, edit and delete routes. They have their own per-webhook buckets.

A global denial has global: true in the body and the X-RateLimit-Global: true header. It never revokes the credential.

Rate limit response object¶

The 429 body has the members of the ordinary error response and two more.

{
  "error": "429 Too Many Requests",
  "code": "RATE_LIMITED",
  "message": "Hız sınırlamasına takıldın. 1 saniye sonra tekrar dene.",
  "global": false,
  "retry_after": 0.428
}

A slowmode denial answers 400 SLOWMODE_RATE_LIMITED instead.

Rate limit headers¶

TEBHOS sends rate limit headers only on a 429 response. A successful response carries none of them, so track your own request rate or simply handle 429.

The API exposes these headers to cross-origin browser clients, so a web client can read them. The body's retry_after remains the most precise value.

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Scope: user
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790000010
X-RateLimit-Reset-After: 9.5
X-RateLimit-Bucket: 5f0c1d2e3a4b5c6d
Content-Type: application/json

Handling rate limits¶

async function tebhosFetch(url, init, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const body = await res.json().catch(() => ({}));
    const waitSeconds = body.retry_after ?? Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, waitSeconds * 1000));
  }
  throw new Error("Rate limited too many times");
}

import time, requests

def tebhos_request(method, url, attempts=5, **kwargs):
    for _ in range(attempts):
        res = requests.request(method, url, **kwargs)
        if res.status_code != 429:
            return res
        try:
            wait = res.json().get("retry_after")
        except ValueError:
            wait = None
        time.sleep(wait or float(res.headers.get("Retry-After", 1)))
    raise RuntimeError("Rate limited too many times")

Slowmode¶

Slowmode limits how often one account sends a message in one guild channel. The allowance is one message per rate_limit_per_user seconds configured on the channel, counted separately for each account and channel. It applies only in guild channels whose interval is above zero, and a member holding BYPASS_SLOWMODE (which includes the guild owner and ADMINISTRATOR) is exempt.

A denied send returns 400 SLOWMODE_RATE_LIMITED, not 429, with a top-level retry_after in fractional seconds and a Retry-After header in whole seconds. It has no X-RateLimit-* header, so a client can tell it apart from a bucket denial by the status and the code.

{
  "error": "400 Bad Request",
  "code": "SLOWMODE_RATE_LIMITED",
  "message": "Yavaş mod hız sınırı.",
  "retry_after": 3.2
}

Limits answering 400¶

Profile field changes are limited to 25 changes per 30 minutes per field. The limit applies separately to the account profile and to each guild member profile. A denial answers 400 INVALID_FORM_BODY with one entry in errors whose code names the field. It has no retry_after and no rate limit header; the remaining wait appears only in the human-readable message.

Bucket reference¶

The tables below list every bucket, with its limit, window and key. Limits are fixed in the API and apply to every account; there is no per-account exemption. Rate limiting can only be switched off in a local development build, never on the production instance.

Authentication¶

Account security¶

Users and relationships¶

Channels and messages¶

Guilds¶

Webhooks¶

Webhook buckets are keyed by the webhook, channel or guild in the path, so every caller shares them.

Applications, OAuth2 and Gateway¶

Other¶

Other surfaces¶

The Gateway has its own limits for identifies, commands and payload sizes; see Gateway limits and rate limits. Uploading bytes to an upload URL is not rate limited by count, but the URL expires; see Attachment uploads.