Son güncelleme 1 Kas 2026

Hatalar

2xx dışındaki her yanıt, aynı dört alana sahip bir JSON zarfıdır. Mantığınızı code alanına göre kurun, message alanını kullanıcılara gösterin, requestId alanını günlüğe yazın ve yalnızca retryable true olduğunda yeniden deneyin.

Hata zarfı

429 Too Many Requests

{  "code": "rate_limit_exceeded",  "message": "API key rate limit exceeded.",  "requestId": "3f2b6c1e-8a4d-4f0e-9b7a-2d5c1e6f8a90",  "retryable": true}

Alan	Tür	Anlamı
`code`	string	`snake_case` biçiminde, kararlı ve makine tarafından okunabilir tanımlayıcı. Mantığınızı buna göre kurun, asla `message` alanına göre değil.
`message`	string	İngilizce, insanlar için okunabilir açıklama. Bir operatöre gösterilmesi güvenlidir; ifadesi değişebilir.
`requestId`	string	Sunucu tarafından üretilen, isteğin UUID’si. Destek ekibiyle iletişime geçtiğinizde ekleyin; isteği günlüklerimizde bulmamızın tek yolu budur.
`retryable`	boolean	Aynı istek değişiklik yapılmadan daha sonra başarılı olabilecekse `true` (istek limitleri, geçici hatalar). Diğer tüm durumlar farklı bir istek gerektirir.

Durum kodları yine de önemlidir

HTTP durumu kaba sınıftır (4xx sizin, 5xx bizim tarafımız); code ise ayrıntılı nedendir. Yalnızca duruma bakan bir istemci, eksik bir kapsam ile modülü içermeyen bir plan arasındaki farkı kaybeder (ikisi de 403).

Hataları ele alma

Aşağıdaki kalıp, RoomScope panelinin kendisinin kullandığı yöntemdir: zarfı ayrıştırın, gövde JSON değilse http_error değerine geri dönün ve yalnızca sunucu hatayı yeniden denenebilir olarak işaretlediğinde üstel bekleme ile yeniden deneyin.

class ApiError extends Error {  constructor(status, { code, message, requestId, retryable }) {    super(message);    Object.assign(this, { status, code, requestId, retryable: Boolean(retryable) });  }} async function call(path, init) {  const res = await fetch(`https://api.toktokdata.live${path}`, init);  if (res.ok) return res.status === 204 ? undefined : res.json();  let envelope = {};  try { envelope = await res.json(); } catch {}  throw new ApiError(res.status, { code: "http_error", message: `Request failed (${res.status})`, ...envelope });} // Retry only when the server says so.async function withRetry(fn, attempts = 3) {  for (let i = 0; ; i++) {    try { return await fn(); }    catch (e) {      if (!(e instanceof ApiError) || !e.retryable || i === attempts - 1) throw e;      await new Promise((r) => setTimeout(r, 500 * 2 ** i));    }  }}

Duruma göre kodlar

Kodlar kararlıdır; yenileri eklenebilir, bu yüzden bilinmeyen bir kodu durumuna göre ele alın. Referanstaki her endpoint, döndürebileceği kodları listeler.

Durum	Kod	Ne zaman	Yeniden denenebilir
400	`validation_error`	Gövde veya bir parametre hatalı biçimli. Mesaj, ilgili alanın adını verir.	hayır
400	`invalid_rankings_input`	Sıralamalar: board eksik, bir değer 128 karakterden uzun ya da limit, leagueTier, period veya liveOnly geçersiz.	hayır
400	`invalid_cursor · invalid_region · invalid_trend_type`	Endpoint’in kabul etmediği bir cursor, bölge (insights’ta iki harf) veya trend türü.	hayır
400	`invalid_live_history_input · invalid_alert_input · invalid_dataset · invalid_format`	Endpoint’e özgü girdi hataları; neyin düzeltilmesi gerektiğini mesaj söyler.	hayır
401	`unauthorized`	Eksik, hatalı biçimli, bilinmeyen, iptal edilmiş veya süresi dolmuş anahtar ya da etkin olmayan bir çalışma alanı. WWW-Authenticate: Bearer ile gönderilir.	hayır
402	`credit_cap_exceeded`	İstek, dönemin harcamasını kredi tavanının üzerine çıkarırdı.	hayır
403	`insufficient_scope`	Anahtar gereken kapsama sahip değil ya da rota yalnızca panele açık.	hayır
403	`module_not_entitled`	Çalışma alanının planı LIVE veya Sorgulama modülünü içermiyor.	hayır
403	`export_format_not_entitled`	Plan bu dışa aktarma biçimini içermiyor.	hayır
404	`not_found`	Yöntem ve yolla eşleşen bir rota yok.	hayır
404	`creator_not_found · video_not_found · live_session_not_found · alert_not_found · export_not_found`	Kaynak mevcut değil veya başka bir çalışma alanına ait.	hayır
409	`export_not_ready · api_key_limit_reached`	Dışa aktarma hâlâ hazırlanıyor ya da planın anahtar sınırına ulaşıldı.	hayır
429	`rate_limit_exceeded`	Anahtar saniye başına istek sınırını aştı. Retry-After değerine uyun.	evet
429	`daily_quota_exceeded`	Anahtar günlük kotasını doldurdu. Retry-After, UTC gece yarısına kadar sayar.	evet
503	`rate_limit_unavailable · metering_unavailable · webhook_unavailable`	Bağımlı bir hizmet çalışmıyor. Artan bekleme süreleriyle yeniden deneyin.	evet
500	`internal_error`	Bizim tarafımızda bir şey başarısız oldu. Artan bekleme süreleriyle yeniden deneyin; bildirirken requestId değerini ekleyin.	evet

Hata olmayan durumlar

Sıralamalarda bilinmeyen veya kapsanmayan bir region hata değildir: yanıt publishable: false, boş bir entries listesi ve nedenini açıklayan bir provenance ile 200 olur.
Toplanmakta olan takip edilenler, takipçiler ve yorumlar 202 ile yanıt verir; yanıtta status: "collecting", bir jobId ve bir Retry-After başlığı bulunur. O kadar saniye sonra yeniden çağırın.

İstek limitlerinin kendi sayfası var: İstek limitleri.

Bu sayfa işinize yaradı mı?