آخر تحديث
الأخطاء
كل استجابة خارج نطاق 2xx هي غلاف JSON بالحقول الأربعة نفسها. اعتمد على code في التفرّع، واعرض message للمستخدمين، وسجّل requestId، ولا تُعد المحاولة إلا عندما تكون قيمة 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 للطلب، يولّده الخادم. أرفقه عند التواصل مع الدعم؛ فهو الطريقة الوحيدة التي نستطيع بها العثور على الطلب في سجلاتنا. |
retryable | boolean | true عندما قد ينجح الطلب نفسه لاحقًا دون تغيير (حدود المعدّل، والأعطال العابرة). أما ما عدا ذلك فيتطلب طلبًا مختلفًا. |
رموز الحالة لا تزال مهمة
حالة HTTP هي الفئة العامة (4xx من جانبك، و5xx من جانبنا)؛ أما
code فهو السبب الدقيق. العميل الذي لا ينظر إلا إلى الحالة يفقد القدرة على التمييز بين نطاق مفقود وباقة لا تتضمن الوحدة (كلاهما 403).التعامل مع الأخطاء
النمط أدناه هو ما تستخدمه لوحة تحكم RoomScope نفسها: حلّل الغلاف، وارجع إلى http_error عندما لا يكون جسم الاستجابة بصيغة JSON، ولا تُعد المحاولة مع تراجع أسّي إلا عندما يصنّف الخادم الخطأ على أنه قابل لإعادة المحاولة.
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)); } }}الرموز حسب الحالة
الرموز ثابتة، لكن قد تُضاف رموز جديدة، لذا تعامل مع أي رمز غير معروف وفق حالته. تسرد كل نقطة نهاية في المرجع الرموز التي يمكن أن تُرجعها.
| الحالة | الرمز | متى | قابل لإعادة المحاولة |
|---|---|---|---|
| 400 | validation_error | جسم الطلب أو أحد المعاملات مشوّه. تذكر الرسالة اسم الحقل. | لا |
| 400 | invalid_rankings_input | التصنيفات: board مفقود، أو قيمة تتجاوز 128 حرفًا، أو قيمة غير صالحة لـ limit أو leagueTier أو period أو liveOnly. | لا |
| 400 | invalid_cursor · invalid_region · invalid_trend_type | مؤشر أو منطقة (حرفان في نقاط نهاية الرؤى) أو نوع اتجاه لا تقبله نقطة النهاية. | لا |
| 400 | invalid_live_history_input · invalid_alert_input · invalid_dataset · invalid_format | أخطاء إدخال خاصة بنقطة النهاية؛ وتوضح الرسالة ما يجب إصلاحه. | لا |
| 401 | unauthorized | مفتاح مفقود أو مشوّه أو غير معروف أو ملغى أو منتهي الصلاحية، أو مساحة عمل غير نشطة. يُرسل مع WWW-Authenticate: Bearer. | لا |
| 402 | credit_cap_exceeded | سيؤدي الطلب إلى تجاوز إنفاق الفترة الحدَّ الأقصى للرصيد. | لا |
| 403 | insufficient_scope | المفتاح يفتقر إلى النطاق، أو أن المسار خاص بلوحة التحكم وحدها. | لا |
| 403 | module_not_entitled | باقة مساحة العمل لا تتضمن وحدة LIVE أو وحدة البحث (Lookup). | لا |
| 403 | export_format_not_entitled | الباقة لا تتضمن صيغة التصدير هذه. | لا |
| 404 | not_found | لا يوجد مسار يطابق الطريقة والمسار المطلوبين. | لا |
| 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 | إحدى الخدمات المعتمَد عليها متوقفة. أعد المحاولة مع تراجع تدريجي. | نعم |
| 500 | internal_error | حدث خطأ من جانبنا. أعد المحاولة مع تراجع تدريجي، وأرفق requestId عند الإبلاغ عنه. | نعم |
حالات ليست أخطاء
- المنطقة (
region) غير المعروفة أو غير المغطاة في التصنيفات ليست خطأً: تكون الإجابة200معpublishable: false، وقائمةentriesفارغة، وكائنprovenanceيوضح السبب. - الحسابات المتابَعة والمتابعون والتعليقات التي لا يزال جمعها جاريًا تُرجع
202معstatus: "collecting"وjobIdوترويسةRetry-After. أعد الاستدعاء بعد انقضاء ذلك العدد من الثواني.
لحدود المعدّل صفحة خاصة بها: حدود المعدّل.
هل كانت هذه الصفحة مفيدة؟