نظرة عامة
يخضع استخدام API لحدود الاستخدام. تقيّد هذه الحدود عدد الطلبات أو الرموز أو أوجه الاستخدام الأخرى خلال فترة محددة.
قد تشير استجابة 429 إلى حدّ استخدام مؤقت، أو نفاد الرصيد المدفوع مسبقًا، أو بلوغ حدّ الإنفاق أو الاستخدام. تحقّق من تفاصيل الخطأ قبل إعادة المحاولة أو تغيير إعدادات الفوترة.
حدّد السبب
اقرأ رسالة الخطأ والقيمة error.code عند توفرها. قد تستخدم الأخطاء المتعلقة بالفوترة القيمة العامة error.type وهي insufficient_quota.
| الخطأ أو الرمز | ما معناه | ما يجب فعله |
| بلوغ حدّ الاستخدام للطلبات أو الرموز | تتجاوز الطلبات حدّ استخدام ساريًا. | نظّم وتيرة الطلبات واتّبع إرشادات إعادة المحاولة أدناه. |
| credit_balance_exhausted | لم يتبقَّ لدى المؤسسة أي رصيد استخدام مدفوع مسبقًا. | أضف رصيد استخدام من إعدادات فوترة API. |
| organization_usage_limit_exceeded | بلغت المؤسسة حدّ الاستخدام الذي خصصته OpenAI لها. | اطلب اعتماد حدّ استخدام أعلى. |
| organization_spend_limit_exceeded | بلغت المؤسسة حدّ الإنفاق المفروض عليها. | زِد الحدّ أو أزِله، أو انتظر إعادة الضبط الشهرية. |
| project_spend_limit_exceeded | بلغ المشروع حدّ الإنفاق المفروض عليه. | زِد حدّ المشروع أو أزِله، أو انتظر إعادة الضبط الشهرية. |
لا تؤدي إعادة المحاولة بعد خطأ في الفوترة أو الإنفاق أو الحصة إلى استعادة الوصول. عالج أولًا مشكلة الرصيد أو الحدّ المشار إليهما. قد يستغرق تطبيق تغييرات حدود الإنفاق المفروضة بعض الوقت.
يتطلب تغيير حدّ الإنفاق إذنًا لإدارة إعدادات المؤسسة أو المشروع المعني. إذا لم يكن لديك حق الوصول، فاطلب المساعدة ممن يدير هذه الإعدادات.
لشراء رصيد استخدام مدفوع مسبقًا، راجع: إعداد فوترة API المدفوعة مسبقًا وإدارتها.
للتعرّف على عناصر التحكم المختلفة في الإنفاق، راجع دليل حدود إنفاق API.
تحقّق من حدود الاستخدام السارية
انتقل إلى صفحة الحدود الخاصة بمؤسستك لمراجعة مستوى استخدامها وحدودها الحالية.
قد تسري حدود الاستخدام على مستوى المؤسسة والمشروع. وليست حصصًا مخصصة لكل مستخدم على حدة. تختلف الحدود أيضًا حسب النموذج، وتشترك بعض عائلات النماذج في حدّ واحد.
تحقّق من الحدّ الذي يشير إليه الخطأ. على سبيل المثال، يُعد حدّ الطلبات في الدقيقة منفصلًا عن حدّ الرموز في الدقيقة. قد تبلغ أحدهما بينما تظل دون الآخر.
تأكّد من المؤسسة المستخدمة في طلبك
إذا كنت عضوًا في عدة مؤسسات، فتأكّد من أن طلباتك تستخدم المؤسسة والمشروع المقصودين.
إذا كان مفتاح API يستخدم مؤسسة افتراضية، فتحقّق من إعداد المؤسسة الافتراضية. قد تختلف ترتيبات الفوترة ومستويات الاستخدام باختلاف المؤسسة.
تقليل أخطاء حدود الاستخدام المؤقتة
نظّم وتيرة الطلبات وتجنّب الدفعات المفاجئة
وزّع الطلبات على مدة زمنية بدلًا من إرسال عدد كبير منها دفعة واحدة.
قد تُفرض حدود الاستخدام خلال فترات أقصر من المدة المعروضة. على سبيل المثال، قد يُفرض حدّ يبلغ 60 طلبًا في الدقيقة أيضًا على فترات مدتها ثانية واحدة. لذلك، قد تؤدي دفعة قصيرة من الطلبات إلى ظهور خطأ حتى إذا بدا متوسط استخدامك أقل من حدّ الدقيقة الواحدة.
قد تسهم المطالبات الطويلة والسماح بعدد كبير من رموز الإخراج دون حاجة في حدوث أخطاء معدل الرموز.
أعِد المحاولة بعد مهلة
بالنسبة إلى أخطاء حدود الاستخدام المؤقتة:
تحقّق من وجود عنوان الاستجابة Retry-After.
إذا تضمّن العنوان مهلة صالحة، فانتظر هذه المدة على الأقل قبل إعادة المحاولة.
إذا كان العنوان مفقودًا أو غير صالح، فاستخدم التراجع الأُسّي مع التذبذب: زِد المهلة بعد كل محاولة غير ناجحة وأضف مهلة عشوائية قصيرة.
ضع حدًا لعدد مرات إعادة المحاولة ولإجمالي الوقت المستغرق فيها.
تعيد حِزم SDK الرسمية من OpenAI تلقائيًا محاولة الأخطاء المؤهلة المتعلقة بحدود الاستخدام، وتلتزم بالعنوان Retry-After عند وجوده. ضع عمليات إعادة المحاولة هذه في الحسبان قبل إضافة حلقة أخرى لإعادة المحاولة.
تُحتسب الطلبات غير الناجحة ضمن حدود الدقيقة الواحدة. قد تؤدي إعادة إرسال الطلب نفسه باستمرار إلى إطالة المشكلة.
للحصول على إرشادات وأمثلة للتنفيذ، راجع دليل حدود استخدام API. راجع أي مكتبة خارجية لإعادة المحاولة قبل استخدامها في تطبيقك.
راجع حجم المطالبة والإخراج
أزِل من مطالباتك التعليمات غير الضرورية والسياق المتكرر والأمثلة. اختبر المطالبة المعدّلة للتأكّد من أنها لا تزال تنتج النتيجة المطلوبة.
استخدم مَعلمة رموز الإخراج التي تدعمها نقطة النهاية والنموذج:
تستخدم Chat Completions المَعلمة max_completion_tokens.
تستخدم Responses المَعلمة max_output_tokens.
تجنّب تعيين حدّ أعلى بكثير مما يحتاج إليه الطلب. تشمل هذه المَعلمات رموز الاستدلال والإخراج المرئي، لذا ضع كليهما في الحسبان عند استخدام نموذج استدلال.
راجع مستوى استخدامك
إذا استمرت الأخطاء بعد تقليل دفعات الطلبات ومراجعة استخدام الرموز، فتحقّق من صفحة الحدود لمعرفة الطرق المتاحة لزيادة حدودك.
مع زيادة الإنفاق على API، قد تنقل OpenAI المؤسسة تلقائيًا إلى مستوى استخدام أعلى. يؤدي ذلك عادةً إلى زيادة حدود الاستخدام في معظم النماذج.
يختلف حدّ الاستخدام الشهري المعتمد عن حدود استخدام الطلبات والرموز. لا ينبغي اعتبار زيادة أحدهما تأكيدًا على تغيّر الآخر.
إذا استمرت المشكلة
قبل تصعيد المشكلة
احتفظ برسالة الخطأ كما هي، وأي رمز خطأ، ومعرّفات الطلبات ذات الصلة، ووقت وقوع الخطأ مع منطقتك الزمنية، والحدّ ذي الصلة الظاهر في حسابك. دوّن الخطوات التي جرّبتها بالفعل.
التواصل مع دعم OpenAI
تواصل مع دعم OpenAI عبر مركز المساعدة إذا تعذّر عليك حل المشكلة بعد التحقّق من الحدّ المشار إليه. لا تُدرج مفاتيح API أو أي أسرار مصادقة أخرى.