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