خطأ rate_limit_error من Anthropic: المعنى والسبب والحل

سببان للخطأ

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

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

محتوى الرد

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Your account has hit a rate limit."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

فرّع بناءً على حقل type. يُظهر SDK بايثون هذا بصيغة anthropic.RateLimitError، فالتقط صنف الاستثناء؛ نصوص الرسائل صياغة لا عقد. كل رد يحمل أيضاً ترويسة request-id مسبوقة بـ req_ تكشفها الـ SDKs، وحين يتحول سؤال عن الحدود إلى تذكرة دعم، يكون ذلك المعرّف هو الفارق بين جواب سريع وآخر بطيء.

اضبط التزامن قبل الإرسال

تعالج فترات الانتظار الخطأ بعد وقوعه، لكن تحديد عدد الطلبات المتزامنة يمنع كثيراً من الحالات من الأصل. استخدم مجموعة ثابتة من العمال أو محدِّد تزامن بسيط، ثم ارفع الحد تدريجياً بعد مراقبة النتائج:

# Python: بركة عمّال تحوّل الدفعات إلى تدفّق ثابت
import asyncio
import anthropic

client = anthropic.AsyncAnthropic()
gate = asyncio.Semaphore(8)        # سقف الطلبات الجارية؛ اضبطه على فئتك

async def ask(prompt: str):
    async with gate:
        return await client.messages.create(
            model="claude-haiku-4-5",
            max_tokens=512,
            messages=[{"role": "user", "content": prompt}],
        )

async def run(prompts):
    return await asyncio.gather(*(ask(p) for p in prompts))

تنتج مجموعة ثابتة من ثمانية عمال تدفقاً محدوداً حتى لو تراكمت المهام في الطابور. ارفع العدد على مراحل، وراقب أخطاء 429 ومعدل الإنجاز قبل كل زيادة.

خفّض الحمل من دون التأثير في الجودة

إذا تكررت أخطاء 429 طوال اليوم، فغالباً تجاوز الاستخدام سعة الخطة. استخدم التخزين المؤقت للتعليمات المتكررة، وانقل المهام التي تحتمل الانتظار إلى Batch API، ووجّه الطلبات البسيطة إلى Claude Haiku 4.5 حين يلائم المهمة. استخدم الحاسبة لمقارنة أثر هذه الخيارات على الفاتورة.