تخطَّ إلى المحتوى

الأخطاء وإعادة المحاولة

تُرجع الأخطاء التجارية code وmessage على المستوى الأعلى من جسم الاستجابة. عادةً ما يكون detail مطابقًا لـ message، لكنه قد يكون شرحًا مختلفًا وأقصر (كما هو موضح أدناه)؛ يُعرض message للمستخدمين. الرسائل باللغة الصينية:

{
"code": "CONCURRENCY_LIMITED",
"message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交",
"detail": "排队文件完成一部分后可继续提交"
}

بعض الأخطاء التجارية تُرجع code فقط. أما حالات فشل التحقق فتُرجع 422 مع قائمة بأخطاء الحقول في detail:

{
"detail": [
{ "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
]
}

عالج الأخطاء أولاً باستخدام الحالة HTTP، ثم باستخدام code: تُرجع العديد من الأخطاء فقط الرمز العام UNKNOWN_ERROR، ولا يحمل سوى بعضها رمزًا محددًا code (مثل حالات 429 الموضحة أدناه). سجّل رأس الاستجابة X-Request-Id لاستكشاف الأخطاء وإصلاحها.

الحالةالمعنىنصائح
400طلب غير صالح، على سبيل المثال الإعداد المختار غير متاحصحّح الطلب؛ لا تُعد المحاولة
401المؤهلات مفقودة أو غير صالحة أو منتهية الصلاحية أو مُلغاةتغيير بيانات الاعتماد
402الرصيد (بعد خصم الدين) لا يتجاوز عتبة الوظيفة، أو أنه سالب؛ وفي حالة وجود مفتاح واجهة برمجة التطبيقات، قد يكون الميزانية المتبقية للمفتاح منخفضة جدًا.قم بتجديد الرصيد (أو زيادة ميزانية المفتاح)، ثم أعد الإرسال
403لا تسمح حدود المفتاح بهذه العملية (على سبيل المثال، إعداد الترجمة غير مسموح به)، أو أن الحساب معطّل، أو يجب تنفيذ العملية في متصفح مسجّل الدخول (مثل إدارة مفاتيح واجهة برمجة التطبيقات).تحقق من الإعدادات الرئيسية أو استخدم الموقع الإلكتروني
404المورد غير موجود، أو تم حذفه، أو ينتمي إلى حساب آخر (كل الحالات الثلاث تبدو متطابقة).تحقق من المعرّف
409تم استخدام مفتاح التكرارية لطلب مختلف، أو أن حالة المورد لا تسمح بتنفيذ العملية.استعلام عن العملية الأصلية، ثم اتخاذ القرار
410المورد أو نقطة النهاية لم تعد موجودة بشكل دائم، على سبيل المثال نقطة نهاية تم إيقافها أو مهمة حُذفت باستخدام مفتاح التكرارية.لا تُعد المحاولة
413يتجاوز الملف أو جسم الطلب الحد المسموح بهاستخدم ملفًا أصغر
415تنسيق الملف غير مدعوماستخدم تنسيقًا آخر
422فشل التحقق، أو أن الملف فارغ أو لا يحتوي على أي شيء لمعالجتهصحّح الحقول؛ لا تُعد المحاولة تلقائيًا
429معدل، حجم قائمة الانتظار أو الميزانية محدودةانظر أدناه
5xxخطأ مؤقت في الخدمةالتأخير الأسي مع حد أقصى لعدد المحاولات
codeالمعنىماذا يجب فعله
RATE_LIMITEDعدد كبير جدًا من الطلباتانتظر Retry-After، ثم أعد المحاولة
CONCURRENCY_LIMITEDهناك عدد كبير جدًا من مهام ترجمة الملفات في قائمة الانتظارانتظر Retry-After، أو انتظر انتهاء بعض المهام
AUTH_API_KEY_QUOTA_EXCEEDEDتم استنفاد ميزانية المفتاحلا تُجرِّب مرة أخرى إلا بعد رفع الميزانية

يجب التعامل مع 429 بدون Retry-After باستخدام خوارزمية الانتظار الأُسي.

استراتيجية إعادة المحاولة

Section titled “استراتيجية إعادة المحاولة”
  • يمكن إعادة محاولة الاستعلامات مباشرةً.
  • عند إعادة محاولة طلب إنشاء، استخدم نفس Idempotency-Key ونفس النص exactly؛ واستخدم مفتاحًا جديدًا لكل عملية إرسال جديدة.
  • بعد فشل عملية الرفع، اطلب عنوان رفع جديد.
  • حدد مهلات الاتصال والقراءة وإجمالي المهلات لكل طلب، وأضف تذبذبًا عشوائيًا إلى عمليات إعادة المحاولة، وحدد الحد الأقصى لعدد المحاولات.
import random
import time
for attempt in range(5):
response = call_api()
if response.status_code not in {429, 500, 502, 503, 504}:
break
if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
time.sleep(delay + random.random())