جدول المحتويات
هل سبق أن توقّفت في منتصف مهمة داخل Claude Code بسبب خطأ كهذا؟
API Error: 529 {"type":"error","error":
{"type":"overloaded_error","message":"Overloaded"}}
# or
API Error: 500 Internal server error.529 Overloaded يعني أن واجهة Anthropic API محمّلة بأكثر من طاقتها مؤقتًا (مزدحمة)، أما 500 فيعني وقوع خطأ غير متوقّع داخل الخادم. كلاهما من جانب الخادم — والأهم من ذلك أنهما ليسا خطأً في طلبك أو إعداداتك، وليسا نفادًا لحصتك من الاستخدام. تنصّ الوثائق الرسمية صراحةً على أن «الخطأ 529 ليس حدّ استخدامك ولا يُحتسب من حصتك». بعبارة أخرى، هذه أخطاء تُحَل عادةً بـ«انتظر لحظة ثم أعد المحاولة».
النقاط الأساسية أولًا. (1) 529/500 من جانب الخادم — وليست خطأك (ولا تستهلك حصتك). (2) Claude Code يعيد المحاولة تلقائيًا حتى 10 مرات بتراجع أسّي (exponential backoff) قبل أن يُظهر لك أي شيء — فحين تظهر الرسالة الودودة، تكون تلك المحاولات قد استُنفدت بالفعل. (3) العلاج هو «راجع صفحة الحالة → انتظر → بدّل النموذج بـ/model». تُدار الطاقة لكل نموذج على حدة، فحتى عندما يكون Opus مزدحمًا، كثيرًا ما يمر Sonnet.
هذا من جانب الخادم، وليس خطأك
— Claude Code يعيد المحاولة بالفعل قبل أن يُظهر لك أي شيء
لذا فالعلاج هو «انتظر وأعد المحاولة / بدّل بـ/model / راجع status.claude.com».
لا توجد عمليًا أي شيفرة أو إعداد لإصلاحه.
1. ما الذي يخبرك به هذا الخطأ
HTTP 529 (overloaded_error / الرسالة "Overloaded") علامة على أن واجهة Anthropic API محمّلة بأكثر من طاقتها مؤقتًا. الوصف الرسمي حرفيًا هو أن «الواجهة محمّلة بأكثر من طاقتها مؤقتًا» وأنها «قد تحدث عندما تشهد الواجهات حركة مرور عالية عبر جميع المستخدمين». وهذا يعني أنها ليست خطأ شخص بعينه، بل أن الطلب الإجمالي تجاوز العرض لفترة وجيزة.
HTTP 500 (api_error) هو خطأ داخلي غير متوقّع في جانب Anthropic. تقول الوثائق إنه «ليس ناتجًا عن مطالبتك (prompt) أو إعداداتك أو حسابك». ويرتبط به 504 (timeout_error) حين تنتهي مهلة طلب طويل (لاحظ أن Anthropic توثّق 504، بينما يأتي 502/503 عادةً من بنية تحتية أعلى في السلسلة مثل البوابات).
النقطة الجوهرية: «529 و500 مشكلتان من جانب الخادم ولا تستهلكان حصة استخدامك.» فهما مختلفان تمامًا عن usage limit reached الخاص بحصة الخطة، وعن حدّ المعدّل الخاص بك 429 (نوضّح الفرق في §4). لذلك لا داعي للتأهّب لإصلاح شيفرة أو إعدادات — الافتراضي هو «انتظر وأعد المحاولة».
2. Claude Code يعيد المحاولة نيابةً عنك بالفعل
في الواقع، قبل أن ترى رسالة الخطأ أصلًا، يكون Claude Code قد ظلّ يعيد المحاولة خلف الكواليس. ووفقًا للوثائق الرسمية —
سلوك إعادة المحاولة التلقائية
أخطاء الخادم، واستجابات الحمل الزائد (overloaded)، ومُهَل الطلبات المنتهية، وكبح 429 المؤقت، والاتصالات المنقطعة، يُعاد محاولتها جميعًا حتى 10 مرات بتراجع أسّي. أثناء إعادة المحاولة، تُظهر أداة الدوران عدًّا تنازليًا بصيغة Retrying in Ns · attempt x/y. وبحلول الوقت الذي تظهر فيه سلسلة API Error: الودودة، تكون تلك المحاولات العشر قد استُنفدت.
لذا فإن «ظهر 529 لوهلة لكنه واصل العمل» أمر طبيعي — إذ امتصّته إعادة المحاولة التلقائية. وعلى العكس، إن وصلت إلى الرسالة الودودة («Repeated 529 Overloaded errors … try again in a moment. If it persists, check https://status.claude.com») فهذه علامة على أن الحمل سيّئ لدرجة أن حتى إعادة المحاولة لم تتعافَ منه. يمكنك ضبط عدد المحاولات بـCLAUDE_CODE_MAX_RETRIES (الافتراضي 10) والحدّ الأقصى لكل طلب بـAPI_TIMEOUT_MS (الافتراضي 600000 مللي ثانية = 10 دقائق) — اخفض العدد للفشل السريع في السكربتات، وارفعه للانتظار خلال عطل أطول.
3. ما الذي يمكنك فعله
الخطوات في حالة 529/500 بسيطة جدًا في الواقع. جرّبها بالترتيب.
انتظر، بدّل، تحقّق
/feedback (أرفق request_id لتسريع التحقيق).
محتار؟ 1) انتظر → 2) بدّل بـ/model → 3) راجع الحالة.
التحوّل إلى ساعات خارج الذروة يساعد أيضًا. لا يوجد عمليًا أي إعداد لإصلاحه.
ملاحظة: الرسالة «Server is temporarily limiting requests» موصوفة رسميًا أيضًا بأنها «كبح قصير الأمد من جانب الخادم لا علاقة له بحدّ استخدامك.» وهي بدورها تزول بانتظار قصير، وتختلف عن usage limit الخاص بحصة الخطة.
4. التمييز بينه وبين الأخطاء المتشابهة
عائلة «لقد توقّف» قد تكون لها أسباب متعاكسة. قسّمها أولًا بحسب «من جانب الخادم أم من جانبك؟»
| الخطأ | مشكلة من؟ | يستهلك الحصة؟ | العلاج الرئيسي |
|---|---|---|---|
| 529 Overloaded | من جانب الخادم (طاقة، يؤثّر على الجميع) | لا | انتظر وأعد المحاولة، /model، راجع الحالة |
| 500 / 504 | من جانب الخادم (خطأ داخلي / انتهاء مهلة) | لا | أعد المحاولة؛ وإن استمر، /feedback |
| 429 Rate limit | من جانبك (حدّ معدّل مفتاح API الخاص بك) | نعم (معدّلك) | أبطئ، ارفع الـ tier، انتظر مدة retry-after |
| usage limit reached | من جانبك (مخصّصات خطة Pro/Max) | نعم (الخطة) | انتظر إعادة التعيين؛ الحلول |
| 400 Invalid request | من جانبك (طلب غير صحيح) | لا | أصلح جسم الطلب |
قاعدة للحفظ: 5xx (بما فيها 529) من جانب الخادم = يزول إن انتظرت. 429 وusage limit يتعلّقان بـ«كمّيتك» = اضبط المعدّل أو الخطة. 400 يتعلّق بـ«محتواك» = أصلح الطلب. 429 و529 يسهل الخلط بينهما بوجه خاص، لكن 429 يحمل ترويسة retry-after ويستهلك الحصة، بينما 529 لا يحمل ترويسة ولا يستهلك حصة — فهما شيئان مختلفان. وللاطلاع على أخطاء Claude Code الشائعة الأخرى، راجع مجموعة الأخطاء.
5. للمطورين (API/SDK)
إن كنت تشغّل تطبيقك الخاص على الـ API/SDK، فالتصميم الصحيح يعامل 529/500 على أنهما «حدث عابر يمكن أن يقع عادةً».
(1) ترفع حزم SDK الرسمية استثناءات مُصنّفة (OverloadedError، InternalServerError، إلخ) وتعيد محاولة الأخطاء العابرة تلقائيًا بتراجع أسّي — التقط أصناف الاستثناءات، لا مطابقات السلاسل النصية. (2) إن أعدت المحاولة بنفسك، فاستخدم «تراجعًا أسّيًا + jitter». (3) ترويسة retry-after موجودة في 429 لكنها غير موجودة في 529، لذا انتظر في حالة 529 بتراجعك الخاص لا بتوقيت مبني على الترويسة. (4) جهّز نموذجًا احتياطيًا (يوفّر Claude Code خيار --fallback-model). (5) زِد حركة المرور تدريجيًا لتجنّب «حدّ التسارع» في 429 بعد ارتفاع مفاجئ في الاستخدام. وإن احتجت توافرًا ثابتًا، فإن Priority Tier وMessage Batches API خياران أيضًا. وللأساسيات، راجع ما هي واجهة AI API.
6. ارتفاع عابر أم عطل (Incident)؟
الخطأ نفسه 529/500 يعني أمورًا مختلفة بحسب ما إذا كان «ارتفاعًا يتلاشى فورًا» أم «انقطاعًا متواصلًا يتكرّر».
الارتفاع العابر (واحد أو بضعة تزول عند إعادة المحاولة) ضمن النطاق الطبيعي لتذبذب الطلب. تمتصّه إعادة المحاولة التلقائية عادةً، ولا شيء لإصلاحه من جانبك. أما «Repeated 529»، أو 500 يصمد أمام إعادة المحاولة، فعلامة على وجوب الاشتباه بعطل قائم — راجع أولًا status.claude.com، وإن كان الانقطاع معلنًا فإن انتظار التعافي هو التصرّف الصحيح الوحيد. وإن استمر 500 دون عطل معلن، فأبلغ عبر /feedback مع request_id. في كلتا الحالتين، كل ما يمكن للمستخدم فعله حيال 529/500 هو «إعادة المحاولة، والتبديل بـ/model، ومراجعة الحالة، والإبلاغ» — وهذا حقًا يكفي.
الخلاصة
إن «API Error: 529 Overloaded» و«500 Internal server error» في Claude Code هما حدثان من جانب الخادم، حيث تكون واجهة Anthropic API محمّلة بأكثر من طاقتها مؤقتًا أو تعرّضت لخطأ داخلي. وهما ليسا خطأً في طلبك أو إعداداتك، وليسا نفادًا لاستخدامك، ولا يستهلكان أي حصة. يعيد Claude Code المحاولة تلقائيًا حتى 10 مرات بتراجع أسّي قبل أن يُظهر لك أي شيء؛ والرسالة الودودة تعني أن تلك المحاولات قد استُنفدت.
العلاج بسيط: (1) انتظر وأعد المحاولة ← (2) بدّل النموذج بـ/model (الطاقة لكل نموذج على حدة) ← (3) راجع status.claude.com ← (4) /feedback إن استمر 500. وهما مختلفان عن 429 (معدّلك) وusage limit (خطتك)، و529 لا يحمل retry-after. وعلى المطورين أن يصمّموا حوله بـإعادة المحاولة التلقائية في الـ SDK، والتراجع الأسّي + jitter، ونموذج احتياطي. وإن تكرّر، فاشتبه بعطل وراجع صفحة الحالة — في كلتا الحالتين، لا توجد عمليًا أي شيفرة أو إعداد لإصلاحه. ذات صلة: حلول usage limit، مقارنة Opus/Sonnet/Haiku، مجموعة أخطاء Claude Code.
الأسئلة الشائعة
Q. هل «529 Overloaded» ناتج عن خطأ مني أو من شيفرتي؟
A. لا — إنها مشكلة من جانب الخادم. يعني 529 أن واجهة Anthropic API محمّلة بأكثر من طاقتها مؤقتًا (ازدحام عبر جميع المستخدمين)؛ ولا دخل لطلبك أو إعداداتك أو حسابك. تنصّ الوثائق صراحةً على أن «الخطأ 529 ليس حدّ استخدامك ولا يُحتسب من حصتك.» وعادةً ما يزول إن انتظرت لحظة ثم أعدت المحاولة.
Q. يطلب مني الإعادة باستمرار — هل أكرّر الضغط بنفسي بكثافة؟
A. لا عمومًا. يعيد Claude Code المحاولة بالفعل تلقائيًا حتى 10 مرات بتراجع أسّي قبل إظهار الخطأ (Retrying in Ns · attempt x/y). وقد ظهرت الرسالة الودودة لأن تلك المحاولات العشر قد استُنفدت. انتظر قليلًا، ومع مطالبة طويلة اكتب فقط «حاول مرة أخرى» لإعادة التشغيل بالسياق الأصلي. ويمكنك ضبط العدد بـCLAUDE_CODE_MAX_RETRIES.
Q. ما الفرق بين 529 و429؟
A. 529 حمل زائد من جانب الخادم (يؤثّر على الجميع؛ ولا يستهلك أيًّا من حصتك)، بينما 429 هو حدّ معدّلك أنت (تجاوزت RPM مفتاح API الخاص بك، إلخ — يتعلّق بمخصّص معدّلك). علامة فارقة: 429 يحمل ترويسة retry-after، أما 529 فلا. يحتاج 429 إلى تعديل من جانبك (أبطئ، ارفع الـ tier)؛ أما 529 فيحتاج فقط إلى الانتظار وإعادة المحاولة أو التبديل بـ/model.
Q. لماذا ينجح التبديل بـ/model أحيانًا؟
A. لأن الطاقة (الازدحام) تُدار لكل نموذج على حدة. فحتى لو كان Opus تحت حمل عالٍ، قد يمر Sonnet فورًا إن كان لديه متّسع. ويطالبك Claude Code نفسه أحيانًا بالتبديل عند الحمل («Opus is experiencing high load, please use /model to switch to Sonnet»). وحين تكون على عجلة، يكون التبديل إلى نموذج أخف أو مختلف بـ/model حلًا سريعًا.
Q. أتلقّى 529/500 بلا توقّف. ماذا أفعل؟
A. اشتبه بعطل قائم وراجع status.claude.com. إن كان الانقطاع معلنًا، فكل ما يمكنك فعله هو انتظار التعافي. وإن استمر 500 دون عطل معلن، فأبلغ عنه عبر /feedback مع request_id ليتمكّن Anthropic من التحقيق. وبما أن 529/500 حدثان من جانب الخادم، فإنه لا توجد عمليًا أي شيفرة أو إعداد عليك إصلاحه.
