RoomScope

Cập nhật lần cuối

Lỗi

Mọi response không phải 2xx đều là một JSON envelope với cùng bốn trường. Rẽ nhánh theo code, hiển thị message cho người dùng, ghi log requestId, và chỉ thử lại khi retryable là true.

Envelope

429 Too Many Requests
{  "code": "rate_limit_exceeded",  "message": "API key rate limit exceeded.",  "requestId": "3f2b6c1e-8a4d-4f0e-9b7a-2d5c1e6f8a90",  "retryable": true}
TrườngKiểuÝ nghĩa
codestringĐịnh danh ổn định, máy đọc được, viết theo snake_case. Hãy rẽ nhánh theo trường này, đừng bao giờ dựa vào message.
messagestringLời giải thích dành cho người đọc, bằng tiếng Anh. Có thể hiển thị cho người vận hành; câu chữ có thể thay đổi.
requestIdstringUUID của request, do server tạo. Hãy gửi kèm khi liên hệ hỗ trợ; đó là cách duy nhất để chúng tôi tìm thấy request trong log.
retryablebooleantrue khi chính request đó có thể thành công về sau mà không cần thay đổi (giới hạn tốc độ, lỗi tạm thời). Mọi trường hợp khác cần một request khác.
Mã trạng thái vẫn quan trọng
HTTP status là phân loại thô (4xx do phía bạn, 5xx do phía chúng tôi); code là lý do chi tiết. Một client chỉ nhìn status sẽ không phân biệt được giữa thiếu scope và gói không có module (cả hai đều là 403).

Xử lý lỗi

Mẫu dưới đây chính là cách dashboard RoomScope đang dùng: parse envelope, dùng http_error khi body không phải JSON, và chỉ thử lại với exponential backoff khi server đánh dấu lỗi là có thể thử lại.

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.next.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));    }  }}

Code theo trạng thái

Các code là ổn định; code mới có thể được thêm vào, vì vậy hãy xử lý code chưa biết theo status của nó. Mỗi endpoint trong phần tham chiếu liệt kê các code mà nó có thể trả về.

Trạng tháiCodeKhi nàoThử lại được
400validation_errorBody hoặc một tham số sai định dạng. Message nêu tên trường bị lỗi.không
400invalid_rankings_inputBảng xếp hạng: thiếu board, một giá trị dài quá 128 ký tự, hoặc limit, leagueTier, period hay liveOnly không hợp lệ.không
400invalid_cursor · invalid_region · invalid_trend_typeCursor, region (hai chữ cái với insights) hoặc loại xu hướng mà endpoint không chấp nhận.không
400invalid_live_history_input · invalid_alert_input · invalid_dataset · invalid_formatLỗi đầu vào riêng của từng endpoint; message cho biết cần sửa gì.không
401unauthorizedKey bị thiếu, sai định dạng, không xác định, đã thu hồi hoặc hết hạn, hoặc workspace không hoạt động. Gửi kèm WWW-Authenticate: Bearer.không
402credit_cap_exceededRequest sẽ khiến mức chi tiêu của kỳ vượt quá hạn mức credit.không
403insufficient_scopeKey thiếu scope, hoặc route chỉ dành cho dashboard.không
403module_not_entitledGói của workspace không bao gồm module LIVE hoặc Tra cứu.không
403export_format_not_entitledGói không bao gồm định dạng xuất đó.không
404not_foundKhông có route nào khớp với method và path.không
404creator_not_found · video_not_found · live_session_not_found · alert_not_found · export_not_foundTài nguyên không tồn tại hoặc thuộc về workspace khác.không
409export_not_ready · api_key_limit_reachedBản xuất vẫn đang được tạo, hoặc đã đạt giới hạn số key của gói.không
429rate_limit_exceededKey đã vượt số request mỗi giây. Hãy tuân theo Retry-After.có
429minute_rate_limit_exceededWorkspace đã vượt số request mỗi phút (tính chung mọi key). Retry-After đếm tới phút kế tiếp.có
429daily_quota_exceededKey đã dùng hết hạn mức trong ngày. Retry-After đếm tới nửa đêm UTC.có
503rate_limit_unavailable · metering_unavailable · webhook_unavailableMột thành phần phụ thuộc đang gặp sự cố. Thử lại với backoff.có
500internal_errorCó lỗi xảy ra phía chúng tôi. Thử lại với backoff; kèm requestId khi bạn báo lỗi.có

Không phải lỗi

  • Một region không xác định hoặc chưa được phủ trên bảng xếp hạng không phải là lỗi: câu trả lời là 200 với publishable: false, danh sách entries trống và một provenance giải thích lý do.
  • Danh sách đang follow, follower và bình luận đang được thu thập sẽ trả về 202 với status: "collecting", một jobId và header Retry-After. Hãy gọi lại sau đúng số giây đó.

Giới hạn tốc độ có trang riêng: Giới hạn tốc độ.

Trang này có hữu ích không?