التعامل مع الأخطاء

ميز بين رفض الطلب وفشل التفريغ. في الحالة الأولى، لم يقبل API الطلب. وفي الثانية، قبله وبدأت المعالجة، لكنها انتهت لاحقا بحالة failed في حقل status.

بنية رد الخطأ

تأتي أخطاء الطلبات على /v1 بهذه البنية:

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

اكتب منطق معالجة الخطأ بناء على code، لا نص الرسالة. اعرض message للمستخدم، لكن لا تعتمد على ثبات صياغتها. إذا كانت retryable تساوي true، فقد ينجح الطلب نفسه بعد الانتظار.

قد تجد حقولا إضافية إلى جانب retryable توضح ما تحتاج إلى فعله:

الحقل	رمز الخطأ المرتبط به	ما الذي يوضحه؟
`action_url`	`insufficient_minutes`	رابط شراء باقة أو شحن دقائق إضافية.
`minutes_needed`، `minutes_remaining`	`insufficient_minutes`	الدقائق المطلوبة والدقائق المتبقية في رصيدك. تكون المطلوبة `null` إذا لم نعرف المدة بعد.
`supported_platforms`	`unsupported_platform`	قيم المنصات المقبولة وهي `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`.
`missing_chunks`	`upload_incomplete`	أرقام الأجزاء التي لم تصل أثناء الرفع.
`max_bytes`	`media_too_large`	حد حجم الملف المسموح لحسابك بالبايت.
`params`	`invalid_request`	كائن يحدد الحقول غير الصالحة وسبب الخطأ في كل منها، عند فحص body أو query.

لماذا لم يقبل API الطلب؟

رمز HTTP	`code`	هل تعيد المحاولة؟	السبب أو الإجراء المطلوب
400، 422	`invalid_request`	لا	حقل أو معامل ناقص أو غير صالح، أو JSON غير صالح في body. من أمثلته الجمع بين `diarize` و`source: "captions"`، أو بين `reuse_recent` و`webhook_url`.
422	`invalid_url`	لا	أرسل رابطا من YouTube أو X أو TikTok أو Instagram أو Facebook أو Bluesky، أو إحدى المنصات في المصادر والخيارات. تأكد أيضا أن `platform` يطابق الرابط.
422	`unsupported_platform`	لا	أرسلت قيمة غير مدعومة في `platform`.
422	`unsupported_media`	لا	امتداد الملف الذي رفعته غير مدعوم.
401	`unauthorized`	لا	بيانات المصادقة غائبة أو غير صالحة أو انتهت صلاحيتها أو ألغيت. وقد يكون token الرفع غير صالح أو منتهي الصلاحية.
403	`insufficient_scope`	لا	لا يملك OAuth token صلاحية `transcriptions:read` أو `transcriptions:write` المطلوبة.
403	`email_not_verified`	لا	أكد بريدك الإلكتروني أولا لتتمكن من إنشاء تفريغ.
402	`insufficient_minutes`	لا	رصيدك القابل للاستخدام 0، أو لا يكفي لمدة التسجيل.
402	`no_active_plan`	لا	حاولت شحن دقائق إضافية دون باقة مدفوعة نشطة. هذا الخطأ من endpoint الفوترة في لوحة التحكم، لا من endpoints التفريغ.
404	`not_found`	لا	لا يوجد تفريغ بهذا المعرف، أو أنه يتبع فريقا آخر.
409	`upload_incomplete`	لا	لم تصل بعض أجزاء الملف. أرسلها ثم أكد اكتمال الرفع من جديد.
409	`invalid_state`	لا	لم يعد التفريغ في حالة انتظار الرفع؛ لا يمكنك إرسال أجزاء أو تأكيد اكتمالها.
409	`idempotency_conflict`	لا	استخدمت قيمة `Idempotency-Key` سابقا مع معاملات مختلفة.
413	`media_too_large`	لا	تجاوز الملف الحجم المسموح. راجع رفع الملفات.
413	`invalid_request`	لا	تجاوز body بصيغة JSON حد 1 MB. للملفات الكبيرة، يكون الرمز `media_too_large` بدلا منه.
429	`rate_limited`	نعم	تجاوزت عدد الطلبات المسموح في الدقيقة. انتظر عدد الثواني المحدد في `Retry-After`.
429	`too_many_active_jobs`	نعم	بلغت حد التفريغات الجارية أو عمليات الرفع المفتوحة. انتظر المدة المحددة في `Retry-After`.
500	`internal_error`	نعم	واجهنا خطأ داخليا. انتظر قليلا وحاول مجددا.
503	`service_unavailable`	نعم	transcript1 غير متاح مؤقتا. حاول بعد قليل.

إذا اعتمد طلب المتصفح على cookie تسجيل الدخول بدلا من Bearer، نتحقق أيضا من الموقع الذي أرسله. طلب موقع آخر يعيد 403 forbidden_origin. هذا الفحص لا يؤثر في استدعاءات API التي تستخدم ترويسة Authorization.

مع كل 429، تجد في Retry-After عدد الثواني التي يجب انتظارها. حدود كل باقة موضحة في الفوترة وحدود الاستخدام.

متى ترسل الطلب من جديد؟

أعد الطلب نفسه فقط مع retryable: true. ينطبق ذلك على rate_limited وtoo_many_active_jobs وinternal_error وservice_unavailable. انتظر Retry-After إن وجد، وإلا فزد مدة الانتظار بين المحاولات.
إذا كررت POST /v1/transcriptions، احتفظ بقيمة Idempotency-Key نفسها. إذا نجح الطلب الأول، فلن تنشئ تفريغا آخر أو تدفع مرتين.
لبقية الرموز، عالج سبب الخطأ قبل إرسال الطلب مجددا.

إذا فشل التفريغ بعد قبول الطلب

قد يصل رد قبول الطلب ثم يفشل التفريغ لاحقا. عند status=failed، يحتوي الكائن على error: { "code", "message" }. اقرأ error عند متابعة الحالة أو عند استقبال webhook من نوع transcription.failed.

`error.code`	ماذا حدث؟	هل تفيد محاولة أخرى؟
`media_unavailable`	الفيديو غير موجود أو لم يعد متاحا.	لا؛ تحقق من الرابط.
`media_private`	لا يمكن جلب الفيديو لأنه خاص.	لا؛ اختر منشورا عاما، أو فيديو YouTube عاما أو غير مدرج.
`login_required`	لا تتيح المنصة مشاهدة الفيديو دون تسجيل الدخول.	لا؛ فشل دائم لا نعيد محاولته.
`no_audio`	لا يحتوي الفيديو على مسار صوتي.	لا؛ فشل دائم لا نعيد محاولته.
`age_restricted`	يفرض الفيديو قيودا عمرية.	لا؛ ارفع الملف بدلا من الرابط.
`live_stream`	البث ما زال مباشرا، أو لم يبدأ بعد.	انتظر انتهاء البث.
`no_captions`	اخترت `source=captions`، ولم نجد مسار ترجمة نصية مناسبا.	اختر `source: "auto"` أو `"stt"`.
`media_too_long`	تجاوز التسجيل حد تحويل الصوت إلى نص، وهو 5 ساعات.	لا؛ قسم التسجيل إلى ملفات أقصر.
`unsupported_media`	تعذر قراءة الملف أو لم نجد فيه مسارا صوتيا.	لا؛ أرسل ملفا مدعوما.
`no_speech`	لم يُرصد أي كلام.	لا.
`unsupported_language`	لغة التسجيل غير مدعومة.	لا؛ اضبط `language` على رمز مدعوم أو `"auto"`.
`insufficient_minutes`	نفدت الدقائق قبل خصم تكلفة التفريغ.	اشحن دقائق إضافية أولا.
`fetch_failed`	تعذر جلب التسجيل رغم تكرار المحاولة.	نعم، جرب لاحقا.
`transcription_failed`	تعذر تحويل الصوت إلى نص رغم تكرار المحاولة.	نعم، جرب لاحقا.

إذا فشل التفريغ أو ألغيته، لا تدفع شيئا. نعيد إلى رصيدك أي دقائق خصمناها له.