อัปเดตล่าสุด 1 พ.ย. 2569

ข้อผิดพลาด

ทุกผลลัพธ์ที่ไม่ใช่ 2xx เป็นโครงสร้าง JSON ที่มีสี่ฟิลด์เหมือนกันเสมอ ให้แยกกรณีด้วย code แสดง message ให้ผู้ใช้ บันทึก requestId ลง log และลองใหม่เฉพาะเมื่อ retryable เป็น true

โครงสร้างข้อผิดพลาด

429 Too Many Requests

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

ฟิลด์	ชนิด	ความหมาย
`code`	string	ตัวระบุที่คงที่และเครื่องอ่านได้ ในรูปแบบ `snake_case` ให้แยกกรณีด้วยฟิลด์นี้ อย่าใช้ `message`
`message`	string	คำอธิบายภาษาอังกฤษที่คนอ่านเข้าใจได้ แสดงให้ผู้ดูแลระบบเห็นได้อย่างปลอดภัย แต่ถ้อยคำอาจเปลี่ยนแปลงได้
`requestId`	string	UUID ของคำขอที่เซิร์ฟเวอร์สร้างขึ้น ให้แนบมาเมื่อติดต่อฝ่ายสนับสนุน เพราะเป็นวิธีเดียวที่เราจะค้นหาคำขอนั้นใน log ได้
`retryable`	boolean	เป็น `true` เมื่อคำขอเดิมอาจสำเร็จได้ในภายหลังโดยไม่ต้องแก้ไข (ขีดจำกัดอัตราการเรียก ความล้มเหลวชั่วคราว) กรณีอื่นทั้งหมดต้องส่งคำขอที่ต่างออกไป

รหัสสถานะยังสำคัญ

สถานะ HTTP บอกประเภทแบบกว้าง (4xx ฝั่งคุณ 5xx ฝั่งเรา) ส่วน code บอกเหตุผลแบบละเอียด ไคลเอนต์ที่ดูแค่สถานะจะแยกไม่ออกระหว่างการขาดสโคป กับแพ็กเกจที่ไม่มีโมดูล (ทั้งคู่เป็น 403)

การจัดการข้อผิดพลาด

รูปแบบด้านล่างคือสิ่งที่แดชบอร์ด RoomScope ใช้เอง: แยกวิเคราะห์โครงสร้างข้อผิดพลาด ใช้ http_error แทนเมื่อ body ไม่ใช่ JSON และลองใหม่แบบ exponential backoff เฉพาะเมื่อเซิร์ฟเวอร์ระบุว่าข้อผิดพลาดนั้นลองใหม่ได้

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

รหัสตามสถานะ

รหัสต่าง ๆ คงที่ แต่อาจมีรหัสใหม่เพิ่มเข้ามา จึงควรจัดการรหัสที่ไม่รู้จักตามสถานะของมัน แต่ละ endpoint ในเอกสารอ้างอิงจะระบุรหัสที่อาจส่งกลับ

สถานะ	Code	เกิดเมื่อ	ลองใหม่ได้
400	`validation_error`	body หรือพารามิเตอร์ผิดรูปแบบ message จะระบุชื่อฟิลด์	ไม่ได้
400	`invalid_rankings_input`	Rankings: ไม่มี board มีค่าที่ยาวเกิน 128 อักขระ หรือค่า limit, leagueTier, period หรือ liveOnly ไม่ถูกต้อง	ไม่ได้
400	`invalid_cursor · invalid_region · invalid_trend_type`	cursor, region (สองตัวอักษรสำหรับ insights) หรือประเภทเทรนด์ที่ endpoint ไม่รับ	ไม่ได้
400	`invalid_live_history_input · invalid_alert_input · invalid_dataset · invalid_format`	ข้อผิดพลาดของข้อมูลนำเข้าเฉพาะ endpoint โดย message จะบอกว่าต้องแก้ไขอะไร	ไม่ได้
401	`unauthorized`	ไม่มีคีย์ คีย์ผิดรูปแบบ ไม่รู้จัก ถูกเพิกถอน หรือหมดอายุ หรือเวิร์กสเปซไม่ได้ใช้งานอยู่ ส่งพร้อม WWW-Authenticate: Bearer	ไม่ได้
402	`credit_cap_exceeded`	คำขอนี้จะทำให้ยอดใช้จ่ายของรอบเกินเพดานเครดิต	ไม่ได้
403	`insufficient_scope`	คีย์ไม่มีสโคปที่ต้องการ หรือเส้นทางนั้นใช้ได้เฉพาะในแดชบอร์ด	ไม่ได้
403	`module_not_entitled`	แพ็กเกจของเวิร์กสเปซไม่รวมโมดูล LIVE หรือโมดูลค้นหา	ไม่ได้
403	`export_format_not_entitled`	แพ็กเกจไม่รวมรูปแบบไฟล์ส่งออกนั้น	ไม่ได้
404	`not_found`	ไม่มีเส้นทางที่ตรงกับ method และ path	ไม่ได้
404	`creator_not_found · video_not_found · live_session_not_found · alert_not_found · export_not_found`	ไม่มีทรัพยากรนั้น หรือเป็นของเวิร์กสเปซอื่น	ไม่ได้
409	`export_not_ready · api_key_limit_reached`	ไฟล์ส่งออกยังสร้างไม่เสร็จ หรือจำนวนคีย์ถึงขีดจำกัดของแพ็กเกจแล้ว	ไม่ได้
429	`rate_limit_exceeded`	คีย์ส่งคำขอเกินจำนวนต่อวินาที ให้ปฏิบัติตาม Retry-After	ได้
429	`daily_quota_exceeded`	คีย์ใช้โควตารายวันหมดแล้ว Retry-After นับถึงเที่ยงคืน UTC	ได้
503	`rate_limit_unavailable · metering_unavailable · webhook_unavailable`	บริการที่ระบบพึ่งพาอยู่ล่ม ให้ลองใหม่พร้อม backoff	ได้
500	`internal_error`	เกิดข้อผิดพลาดฝั่งเรา ให้ลองใหม่พร้อม backoff และแนบ requestId เมื่อแจ้งปัญหา	ได้

สิ่งที่ไม่ใช่ข้อผิดพลาด

region ที่ไม่รู้จักหรือไม่ครอบคลุมใน rankings ไม่ถือเป็นข้อผิดพลาด ผลลัพธ์จะเป็น 200 พร้อม publishable: false รายการ entries ที่ว่างเปล่า และ provenance ที่อธิบายเหตุผล
รายการที่กำลังติดตาม ผู้ติดตาม และความคิดเห็นที่กำลังเก็บข้อมูลจะตอบกลับเป็น 202 พร้อม status: "collecting", jobId และ header Retry-After ให้เรียกอีกครั้งหลังผ่านไปตามจำนวนวินาทีนั้น

ขีดจำกัดอัตราการเรียกมีหน้าเฉพาะ: ขีดจำกัดอัตราการเรียก

หน้านี้มีประโยชน์หรือไม่