Errors¶

A failed HTTP API request returns a JSON error body with a stable machine-readable code and a human-readable message. Match on code; show message to a person if you like, but never parse it.

Error response¶

A failure with more to report adds members next to these at the top level: a rate limit denial adds global and retry_after, a validation failure can add errors, and a few operations add their own members as documented on their pages.

{
  "error": "404 Not Found",
  "code": "NOT_FOUND",
  "message": "Kanal bulunamadı"
}

Status codes¶

A 5xx response is not the caller's fault. Retry it later with backoff. A 500 always carries the generic message and never includes internal details.

Error code registry¶

These are the values the top-level code field can take. Most failures use one of the generic codes; operations that need a more precise answer use a specific code.

Generic codes¶

Specific codes¶

The message for each code describes the specific situation. Operation pages list the codes each operation can return.

Validation errors¶

A field-level validation failure returns 400 with code set to INVALID_FORM_BODY. It comes in two forms.

With an errors array. When a failure has a machine-readable reason, the body names the field and the reason:

{
  "error": "400 Bad Request",
  "code": "INVALID_FORM_BODY",
  "message": "Hakkımda çok sık değiştirildi; 12 dakika sonra yeniden dene.",
  "errors": [
    {
      "path": "bio",
      "code": "BIO_CHANGED_TOO_MANY_TIMES",
      "message": "BIO_CHANGED_TOO_MANY_TIMES"
    }
  ]
}

Without an errors array. Other validation failures return INVALID_FORM_BODY with only a descriptive message, which names the field and constraint in text.

Validation codes¶

The profile limits apply both to the account profile and to per-guild member profiles. See Rate limits.

Rate limit errors¶

A rate limit denial returns 429 with code set to RATE_LIMITED and two extra members:

{
  "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
}

retry_after is the delay in fractional seconds before one more request is admitted, and global tells whether the global limit produced the denial. Rate limits describes the headers and buckets.

OAuth2 errors¶

The OAuth2 operations use the same error body. Their message is often a short OAuth2-style token such as invalid_token, but clients should still switch on code.

Handling errors¶

• Switch on code. Fall back to the HTTP status only for a response without a JSON body.
• On 401, stop using the credential and obtain a new one.
• On 429, wait retry_after seconds before retrying.
• On 5xx, retry with exponential backoff.
• On any other 4xx, change the request before sending it again.

const res = await fetch("https://tebhos.com/api/v1/channels/1489002177550843904", {
  headers: { Authorization: `Bot ${process.env.TEBHOS_BOT_TOKEN}` },
});

if (!res.ok) {
  const body = await res.json().catch(() => null);
  switch (body?.code) {
    case "RATE_LIMITED":
      await new Promise((r) => setTimeout(r, body.retry_after * 1000));
      break;
    case "NOT_FOUND":
      console.warn("Channel not found or not visible");
      break;
    default:
      throw new Error(`${res.status} ${body?.code ?? "UNKNOWN"}`);
  }
}

import os, time, requests

res = requests.get(
    "https://tebhos.com/api/v1/channels/1489002177550843904",
    headers={"Authorization": f"Bot {os.environ['TEBHOS_BOT_TOKEN']}"},
)

if not res.ok:
    try:
        body = res.json()
    except ValueError:
        body = {}
    code = body.get("code")
    if code == "RATE_LIMITED":
        time.sleep(body["retry_after"])
    elif code == "NOT_FOUND":
        print("Channel not found or not visible")
    else:
        raise RuntimeError(f"{res.status_code} {code}")