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ường | Kiểu | Ý nghĩa |
|---|---|---|
code | string | Đị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. |
message | string | Lờ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. |
requestId | string | UUID 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. |
retryable | boolean | true 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ái | Code | Khi nào | Thử lại được |
|---|---|---|---|
| 400 | validation_error | Body hoặc một tham số sai định dạng. Message nêu tên trường bị lỗi. | không |
| 400 | invalid_rankings_input | Bả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 |
| 400 | invalid_cursor · invalid_region · invalid_trend_type | Cursor, 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 |
| 400 | invalid_live_history_input · invalid_alert_input · invalid_dataset · invalid_format | Lỗi đầu vào riêng của từng endpoint; message cho biết cần sửa gì. | không |
| 401 | unauthorized | Key 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 |
| 402 | credit_cap_exceeded | Request sẽ khiến mức chi tiêu của kỳ vượt quá hạn mức credit. | không |
| 403 | insufficient_scope | Key thiếu scope, hoặc route chỉ dành cho dashboard. | không |
| 403 | module_not_entitled | Gói của workspace không bao gồm module LIVE hoặc Tra cứu. | không |
| 403 | export_format_not_entitled | Gói không bao gồm định dạng xuất đó. | không |
| 404 | not_found | Không có route nào khớp với method và path. | không |
| 404 | creator_not_found · video_not_found · live_session_not_found · alert_not_found · export_not_found | Tài nguyên không tồn tại hoặc thuộc về workspace khác. | không |
| 409 | export_not_ready · api_key_limit_reached | Bản xuất vẫn đang được tạo, hoặc đã đạt giới hạn số key của gói. | không |
| 429 | rate_limit_exceeded | Key đã vượt số request mỗi giây. Hãy tuân theo Retry-After. | có |
| 429 | minute_rate_limit_exceeded | Workspace đã 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ó |
| 429 | daily_quota_exceeded | Key đã dùng hết hạn mức trong ngày. Retry-After đếm tới nửa đêm UTC. | có |
| 503 | rate_limit_unavailable · metering_unavailable · webhook_unavailable | Một thành phần phụ thuộc đang gặp sự cố. Thử lại với backoff. | có |
| 500 | internal_error | Có 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
regionkhô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à200vớipublishable: false, danh sáchentriestrống và mộtprovenancegiải thích lý do. - Danh sách đang follow, follower và bình luận đang được thu thập sẽ trả về
202vớistatus: "collecting", mộtjobIdvà headerRetry-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?