الدرس 3 من 4 · ٨ دقائق

عندما يفشل طلب

تفرّع حسب رمز الخطأ والحالة، ولا تُعِد المحاولة إلا للأخطاء التي قد تنجح لاحقًا.

لكل أخطاء Phaseo نص JSON نفسه على كل نقاط النهاية. كائن error هو الشكل الذي تقرؤه حزم SDK المتوافقة مع OpenAI أصلًا:

{
  "error": {
    "code": "insufficient_funds",
    "message": "...",
    "type": "insufficient_quota",
    "param": null
  },
  "generation_id": "G-...",
  "status_code": 402
}

تفرّع حسب error.code وحالة HTTP، لا حسب نص الرسالة أبدًا. وسجّل generation_id دائمًا.

الحالةالرمز الشائعماذا تفعل
400validation_error، model_requiredأصلح الطلب. يسمّي error.param الحقل.
401unauthorisedتحقّق من المفتاح ومن ترويسة Authorization.
402insufficient_fundsأضف رصيدًا، أو استخدم phaseo/free.
403guardrail_blockedغيّر الطلب أو ضابط الحماية.
404not_foundتحقّق من المسار والمعرّف.
410model_retiredانتقل إلى replacement_model.
429rate_limit_exceeded، key_limit_exceededانتظر Retry-After، ثم أعد المحاولة.
5xxupstream_error، gateway_errorأعد المحاولة مع تأخير متزايد.

لا تُعِد محاولة أخطاء 4xx غير 429 دون تغيير، فهي ستفشل مجددًا. مع 429، انتظر Retry-After (ثوانٍ أو تاريخ HTTP)، أو استخدم تأخيرًا أُسيًّا متزايدًا مع عشوائية. الخطأ key_limit_exceeded دون Retry-After لن يُعاد ضبطه من تلقاء نفسه، فلا تُعِد محاولته. ولا تُعِد محاولة 5xx إلا إذا كان تكرار الاستدعاء آمنًا، وضع حدًا لعدد المحاولات ومهلة إجمالية.

تحقّق من فهمك

يعيد طلبك 401 مع الرمز unauthorised. ماذا يجب أن يفعل كودك؟

طبّق ما تعلّمته

يرسل سكربت دفعات 500 طلب في حلقة. في منتصف الطريق، تبدأ الاستجابات بالعودة كـ 429 مع ترويسة Retry-After: 20. ماذا تغيّر؟

اعرض الإجابة

اجعل السكربت يحترم Retry-After: توقّف نحو 20 ثانية قبل إعادة المحاولة، وارجع إلى تأخير أُسّي متزايد مع عشوائية عندما تغيب الترويسة. وتحقّق من error.code أيضًا: rate_limit_exceeded سيُعاد ضبطه، أما key_limit_exceeded دون Retry-After فلن يُعاد، لذا لا فائدة من إعادة محاولته.

الخلاصة

تفرّع حسب error.code والحالة، وأصلح أخطاء 4xx، ولا تُعِد المحاولة إلا لأخطاء 429 و5xx الآمنة مع تأخير متزايد.

روابط ذات صلة

يُحفظ تقدّمك في هذا المتصفح.

آخر مراجعة: ١٧ نوفمبر ٢٠٢٦