عندما يفشل طلب
تفرّع حسب رمز الخطأ والحالة، ولا تُعِد المحاولة إلا للأخطاء التي قد تنجح لاحقًا.
لكل أخطاء 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 دائمًا.
| الحالة | الرمز الشائع | ماذا تفعل |
|---|---|---|
400 | validation_error، model_required | أصلح الطلب. يسمّي error.param الحقل. |
401 | unauthorised | تحقّق من المفتاح ومن ترويسة Authorization. |
402 | insufficient_funds | أضف رصيدًا، أو استخدم phaseo/free. |
403 | guardrail_blocked | غيّر الطلب أو ضابط الحماية. |
404 | not_found | تحقّق من المسار والمعرّف. |
410 | model_retired | انتقل إلى replacement_model. |
429 | rate_limit_exceeded، key_limit_exceeded | انتظر Retry-After، ثم أعد المحاولة. |
5xx | upstream_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 الآمنة مع تأخير متزايد.روابط ذات صلة
آخر مراجعة: ١٧ نوفمبر ٢٠٢٦