الأخطاء
شكل استجابة الخطأ، وكل رموز الأخطاء التي تعيدها الواجهة البرمجية، والأخطاء التي يمكن إعادة المحاولة بعدها.
لكل خطأ الشكل نفسه بصيغة JSON ورمز ثابت في الحقل code. اعتمد في منطقك على code وحالة HTTP، ولا تعتمد على message: الرسائل مكتوبة للبشر وقد تتغيّر.
شكل استجابة الخطأ
{
"error": {
"code": "validation_failed",
"message": "validation failed",
"request_id": "9f2c4e7a1b3d5f6e8a0c2e4f6a8b0d1c",
"details": {
"fields": [
{ "field": "video_id", "message": "must be a UUID" },
{ "field": "ttl_seconds", "message": "must be at most 86400" }
]
}
}
}| الحقل | المعنى |
|---|---|
code | رمز ثابت للآلة، القائمة أدناه. |
message | وصف قصير للسجلات وللبشر. |
request_id | معرّف هذا الطلب، ويصل أيضًا في ترويسة الاستجابة X-Request-ID. اذكره عند التواصل مع الدعم. |
details.fields | مع validation_failed فقط: كل حقل غير صالح مع السبب. |
تقول أخطاء الخادم (500) دائمًا internal server error: تبقى تفاصيلها في سجلات أوكتا فيديو ويُعثر عليها بمعرّف request_id.
رموز الأخطاء
| الحالة | code | ماذا حدث | ماذا تفعل |
|---|---|---|---|
| 400 | validation_failed | حقل واحد أو أكثر غير صالح. | صحّح الحقول المذكورة في details.fields. |
| 400 | bad_request | تعذّرت قراءة جسم الطلب: JSON غير سليم، أو حقل غير معروف، أو أكثر من قيمة JSON، أو جسم فارغ، أو جسم multipart مفقود. | صحّح الطلب. ترفض الواجهة الحقول غير المعروفة عمدًا حتى لا يمر خطأ إملائي دون أن تلاحظه. |
| 401 | unauthorized | ترويسة AccessKey مفقودة، أو المفتاح خاطئ أو أُعيد إنشاؤه. | تحقّق من المفتاح على خادمك. اقرأ المصادقة. |
| 403 | forbidden | المفتاح صالح لكنه غير مسموح له بهذا الإجراء. | تأكّد أن المورد يتبع مكتبة هذا المفتاح. |
| 404 | not_found | الفيديو أو المجموعة أو المسار غير موجود في هذه المكتبة. | تحقّق من المعرّف ومن مكتبة مفتاحك. |
| 405 | method_not_allowed | المسار موجود بطريقة HTTP أخرى. | راجع الطريقة في مرجع الواجهة البرمجية. |
| 409 | video_not_ready | طلبت رمز تشغيل قبل انتهاء معالجة الفيديو. | انتظر حتى تصبح قيمة encoding_status هي ready. اقرأ حالة المعالجة. |
| 409 | conflict | الطلب يتعارض مع الحالة الحالية. | اقرأ الرسالة، ثم اجلب المورد من جديد. |
| 413 | payload_too_large | جسم الطلب أكبر من الحد. | اقرأ الحدود. |
| 429 | rate_limited | طلبات كثيرة جدًا. | انتظر عدد الثواني في ترويسة Retry-After ثم أعد المحاولة. |
| 500 | internal_error | حدث خطأ من جهة أوكتا فيديو. | أعد المحاولة مع مهلة متزايدة. إن استمر الخطأ فأرسل request_id إلى الدعم. |
أخطاء التشغيل
يتحقق المشغّل من كل رمز OTP عند بدء التشغيل. قد يرى مشاهدوك هذه الأخطاء، ولا تصل إلى خادمك.
code | المعنى |
|---|---|
domain_not_allowed | الصفحة التي تضمّن المشغّل ليست ضمن النطاقات المسموحة للمكتبة. |
country_blocked | دولة المشاهد محظورة بحسب قواعد الدول في المكتبة. |
unauthorized | رمز OTP غير معروف أو استُخدم من قبل أو انتهت صلاحيته. اطلب رمزًا جديدًا لكل مشاهدة للصفحة. |
إعادة المحاولة
- أعد المحاولة بعد
429حين تنقضي مدةRetry-After، وبعد500مع مهلة متزايدة (مثل 1 ث ثم 2 ث ثم 4 ث، حتى 5 محاولات). - لا تُعِد طلبات أخطاء
4xxالأخرى دون تغيير: ستفشل بالطريقة نفسها حتى تصلح الطلب. - الرفع: الرفع الذي يفشل في منتصفه يبدأ من جديد من البداية.
معرّفات الطلبات
تحمل كل استجابة الترويسة X-Request-ID. يمكنك إرسال معرّفك الخاص (حروف ASCII قابلة للطباعة، حتى 128 حرفًا) لتطابق سجلات أوكتا فيديو مع سجلاتك، وإلا تُنشئ أوكتا فيديو معرّفًا. سجّله بجانب كل طلب فاشل.