Hatalar¶

Başarısız bir HTTP API isteği; makinece okunabilen, kararlı bir code ve insanlar için okunabilir bir message içeren JSON hata gövdesi döndürür. Eşleştirme code üzerinden yapılır; message istenirse kişiye gösterilebilir, ancak asla ayrıştırılmamalıdır.

Hata yanıtı¶

Bildirecek daha fazla bilgisi olan bir hata, bunların yanına en üst düzeyde başka üyeler ekler: hız sınırı reddi global ve retry_after ekler, doğrulama hatası errors ekleyebilir ve birkaç işlem de kendi sayfalarında belgelenen kendi üyelerini ekler.

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

Durum kodları¶

5xx yanıtı çağıranın hatası değildir. Geri çekilmeyle (backoff) daha sonra yeniden denenir. 500 her zaman genel mesajı taşır ve asla dahili ayrıntı içermez.

Hata kodu kaydı¶

En üst düzeydeki code alanının alabileceği değerler bunlardır. Hataların çoğu genel kodlardan birini kullanır; daha kesin bir yanıt gerektiren işlemler özel bir kod kullanır.

Genel kodlar¶

Özel kodlar¶

Her kodun message değeri o duruma özgü açıklamayı verir. İşlem sayfaları, her işlemin döndürebileceği kodları listeler.

Doğrulama hataları¶

Alan düzeyindeki bir doğrulama hatası, code değeri INVALID_FORM_BODY olan 400 döndürür. İki biçimde gelir.

errors dizisiyle. Hatanın makinece okunabilir bir nedeni varsa gövde alanı ve nedeni belirtir:

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

errors dizisi olmadan. Diğer doğrulama hataları yalnız açıklayıcı bir message ile INVALID_FORM_BODY döndürür; bu mesaj alanı ve kısıtı metin olarak belirtir.

Doğrulama kodları¶

Profil sınırları hem hesap profiline hem de sunucu başına üye profillerine uygulanır. Bkz. Hız sınırları.

Hız sınırı hataları¶

Hız sınırı reddi, code değeri RATE_LIMITED olan ve iki ek üye taşıyan 429 döndürür:

{
  "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, bir istek daha kabul edilmeden önceki kesirli saniye cinsinden gecikmedir; global ise reddin genel sınırdan kaynaklanıp kaynaklanmadığını belirtir. Başlıklar ve kovalar Hız sınırları sayfasında açıklanır.

OAuth2 hataları¶

OAuth2 işlemleri aynı hata gövdesini kullanır. message değerleri çoğunlukla invalid_token gibi kısa, OAuth2 tarzı bir belirteçtir; ancak istemciler yine de code üzerinden karar vermelidir.

Hataları işleme¶

• code üzerinden karar verilir. HTTP durumuna yalnız JSON gövdesi olmayan yanıtlarda geri dönülür.
• 401 alındığında kimlik bilgisi kullanılmayı bırakılır ve yenisi alınır.
• 429 alındığında yeniden denemeden önce retry_after saniye beklenir.
• 5xx alındığında üstel geri çekilmeyle yeniden denenir.
• Diğer her 4xx durumunda istek, yeniden gönderilmeden önce değiştirilir.

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