الأخطاء وإعادة المحاولة
تُرجع الأخطاء التجارية 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 لاستكشاف الأخطاء وإصلاحها.
HTTP status
Section titled “HTTP status”| الحالة | المعنى | نصائح |
|---|---|---|
400 | طلب غير صالح، على سبيل المثال الإعداد المختار غير متاح | صحّح الطلب؛ لا تُعد المحاولة |
401 | المؤهلات مفقودة أو غير صالحة أو منتهية الصلاحية أو مُلغاة | تغيير بيانات الاعتماد |
402 | الرصيد (بعد خصم الدين) لا يتجاوز عتبة الوظيفة، أو أنه سالب؛ وفي حالة وجود مفتاح واجهة برمجة التطبيقات، قد يكون الميزانية المتبقية للمفتاح منخفضة جدًا. | قم بتجديد الرصيد (أو زيادة ميزانية المفتاح)، ثم أعد الإرسال |
403 | لا تسمح حدود المفتاح بهذه العملية (على سبيل المثال، إعداد الترجمة غير مسموح به)، أو أن الحساب معطّل، أو يجب تنفيذ العملية في متصفح مسجّل الدخول (مثل إدارة مفاتيح واجهة برمجة التطبيقات). | تحقق من الإعدادات الرئيسية أو استخدم الموقع الإلكتروني |
404 | المورد غير موجود، أو تم حذفه، أو ينتمي إلى حساب آخر (كل الحالات الثلاث تبدو متطابقة). | تحقق من المعرّف |
409 | تم استخدام مفتاح التكرارية لطلب مختلف، أو أن حالة المورد لا تسمح بتنفيذ العملية. | استعلام عن العملية الأصلية، ثم اتخاذ القرار |
410 | المورد أو نقطة النهاية لم تعد موجودة بشكل دائم، على سبيل المثال نقطة نهاية تم إيقافها أو مهمة حُذفت باستخدام مفتاح التكرارية. | لا تُعد المحاولة |
413 | يتجاوز الملف أو جسم الطلب الحد المسموح به | استخدم ملفًا أصغر |
415 | تنسيق الملف غير مدعوم | استخدم تنسيقًا آخر |
422 | فشل التحقق، أو أن الملف فارغ أو لا يحتوي على أي شيء لمعالجته | صحّح الحقول؛ لا تُعد المحاولة تلقائيًا |
429 | معدل، حجم قائمة الانتظار أو الميزانية محدودة | انظر أدناه |
5xx | خطأ مؤقت في الخدمة | التأخير الأسي مع حد أقصى لعدد المحاولات |
معالجة الرمز 429
Section titled “معالجة الرمز 429”code | المعنى | ماذا يجب فعله |
|---|---|---|
RATE_LIMITED | عدد كبير جدًا من الطلبات | انتظر Retry-After، ثم أعد المحاولة |
CONCURRENCY_LIMITED | هناك عدد كبير جدًا من مهام ترجمة الملفات في قائمة الانتظار | انتظر Retry-After، أو انتظر انتهاء بعض المهام |
AUTH_API_KEY_QUOTA_EXCEEDED | تم استنفاد ميزانية المفتاح | لا تُجرِّب مرة أخرى إلا بعد رفع الميزانية |
يجب التعامل مع 429 بدون Retry-After باستخدام خوارزمية الانتظار الأُسي.
استراتيجية إعادة المحاولة
Section titled “استراتيجية إعادة المحاولة”- يمكن إعادة محاولة الاستعلامات مباشرةً.
- عند إعادة محاولة طلب إنشاء، استخدم نفس
Idempotency-Keyونفس النص exactly؛ واستخدم مفتاحًا جديدًا لكل عملية إرسال جديدة. - بعد فشل عملية الرفع، اطلب عنوان رفع جديد.
- حدد مهلات الاتصال والقراءة وإجمالي المهلات لكل طلب، وأضف تذبذبًا عشوائيًا إلى عمليات إعادة المحاولة، وحدد الحد الأقصى لعدد المحاولات.
import randomimport 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())