خطأ Gemini ‏RESOURCE_EXHAUSTED: المعنى والسبب والحل

لماذا يظهر الخطأ؟

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

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

الاستجابة

يغلّف Google كل فشل في القالب نفسه: حقل code رقمي يطابق حالة HTTP، ورسالة مقروءة للبشر، وسلسلة حالة gRPC. هذا شكل نموذجي لجسم استجابة 429:

{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED"
  }
}

نص الرسالة يتغير حسب الحصة التي نفدت، لذا تفرّع على حقل status لا على النص.

خفّض المعدل من المصدر

إعادة المحاولة إسعاف أولي. تشكيل الحركة قبل أن تغادر عمليتك هو العلاج، ولا تحتاج مكتبة لذلك:

// JavaScript: حدّ التزامن وباعد بين بدايات الطلبات
function geminiLimiter(maxInFlight = 2, startGapMs = 4000) {
  const queue = [];
  let inFlight = 0;
  let lastStart = 0;

  function pump() {
    if (inFlight >= maxInFlight) return;
    if (queue.length === 0) return;
    const wait = lastStart + startGapMs - Date.now();
    if (wait > 0) { setTimeout(pump, wait); return; }
    lastStart = Date.now();
    inFlight += 1;
    const job = queue.shift();
    job.thunk().then(job.resolve, job.reject)
      .finally(() => { inFlight -= 1; pump(); });
    pump(); // قد تكون هناك فتحة أخرى متاحة
  }

  return (thunk) => new Promise((resolve, reject) => {
    queue.push({ thunk, resolve, reject });
    pump();
  });
}

// 4000ms بين البدايات يحدّك قرب 15 استدعاءً في الدقيقة؛
// اضبط المقبضين على الحدود المنشورة لباقتك
const limited = geminiLimiter(2, 4000);
const reply = await limited(() => model.generateContent(prompt));

كل استدعاء يدخل بصفته دالة مؤجَّلة (thunk)، والبوابة تقرر متى يعمل. مقبضان، كلاهما مضبوط على الأرقام المنشورة لباقتك: كم طلباً يطير في آنٍ واحد، وكم تتباعد بداياتها.

متى تحتاج إلى باقة مدفوعة؟

إذا كان محدِّد المعدل يعمل وما زالت الحصة لا تكفي، فاختر أحد ثلاثة مسارات: اطلب رفع الحصة إذا كان نمط الاستخدام سليماً، أو فعّل الفوترة إذا انتقل التطبيق إلى الإنتاج، أو وجّه المهام المناسبة إلى نموذج آخر. يبلغ سعر Gemini 3.5 Flash المدفوع 1.50$ للإدخال و9.00$ للإخراج لكل مليون توكن في اللقطة المستخدمة هنا. استخدم الحاسبة لتقدير الفاتورة الشهرية، وترتيب النماذج لبناء قائمة بدائل.