OpenAI insufficient_quota: معناه وسببه وحله

لماذا يحدث

يفوتر OpenAI بالرصيد المدفوع مسبقاً وأسقف ميزانية اختيارية. لحظة بلوغ الرصيد القابل للاستخدام صفراً (أو بلوغ سقفك)، تتوقف الـ API عن خدمتك. أربع حالات تنتج كل الحالات تقريباً: نفد رصيد الحساب ببساطة في منتصف الشهر؛ أو سقف ميزانية ضبطته قبل أشهر صار مقيِّداً أخيراً؛ أو انتهت أرصدة التجربة (لها صلاحية)؛ أو مفتاحك يعود لمشروع نفدت حصته بينما لمشروع شقيق مال باقٍ. الأخيرة تلسع الفرق التي تنظّم العمل في مشاريع متعددة وتفترض أن الفوترة مشتركة. ليست كذلك — الحصة تتبع المشروع، والفشل كذلك.

الخطأ الذي سيظهر لك

{
  "error": {
    "message": "You exceeded your current quota, please check your plan and billing details.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

حالة HTTP: 429. تلك الحالة هي الفخ — يرى وسيطُ إعادة المحاولة لديك 429 فيتراجع بأدب، ثم يفشل ثانيةً، إلى الأبد. الجسم، لا الحالة، يخبرك أيّ 429 لديك.

الحارس البرمجي الذي ينقذ ليلتك

افصل الـ 429 على مستوى المعالِج. إخفاقات الحصة تذهب إلى تنبيه؛ وحدود الاستخدام تذهب إلى التراجع:

# Python — route the two 429s differently
from openai import OpenAI, RateLimitError

client = OpenAI()
try:
    r = client.chat.completions.create(model="gpt-5", messages=msgs)
except RateLimitError as e:
    if "insufficient_quota" in str(e):
        alert_oncall("OpenAI billing exhausted — requests halted")
        raise            # retrying is pointless
    sleep_with_backoff() # a real rate limit — this one heals itself

الوقاية

اضبط تنبيه استخدام تحت سقفك، لا عنده. تريد الرسالة قبل أن يشعر الإنتاج بأي شيء. أعطِ كل مشروع ميزانيته الخاصة كي لا تجوّع مهمة دفعية جامحة بقية المشاريع. وإذا ظلت الحصة تتبخر أسرع مما خُطّط، فالفاتورة نفسها هي العلّة: وجّه التدفق الضخم إلى مستوى أرخص بدل أن تطعِم كل شيء لنموذجك الأغلى.