رفع محدودیت استفاده از Claude و خطای Rate Limit

محدودیت‌های استفاده از Claude چیست؟

محدودیت‌های استفاده از Claude در دو سیستم مجزا تعریف می‌شوند و اولین گام، تشخیص این است که کدام‌یک باعث توقف فعالیت شما شده است. اشتراک Claude (شامل Pro، Max، Team یا طرح‌های Enterprise مبتنی بر تعداد کاربر) یک سهمیه استفاده متغیر (rolling) در اختیار شما قرار می‌دهد که بین مدل‌ها مشترک است (به‌جز چند سقف محدود برای خانواده‌های خاص مدل) و با چت Claude نیز به اشتراک گذاشته می‌شود؛ بنابراین در صورت اتمام آن، با پیامی مشابه You've hit your session limit · resets 3:45pm مواجه می‌شوید. طرح‌های Enterprise فعلی که مبتنی بر میزان استفاده هستند، استثنا محسوب می‌شوند: این طرح‌ها سهمیه پیش‌فرض ندارند و تمام استفاده از همان توکن اول با نرخ API محاسبه و صورت‌حساب می‌شود. API سرویس Claude معیار دیگری را اندازه‌گیری می‌کند: سرعت ارسال درخواست‌ها و توکن‌ها که به‌صورت دقیقه‌ای محاسبه می‌شود. این محدودیت با خطای HTTP 429 از نوع rate_limit_error اعمال می‌شود و معمولاً شامل هدر retry-after است که مدت‌زمان انتظار به ثانیه را مشخص می‌کند.

راه‌حل‌های این دو مورد هیچ شباهتی به هم ندارند. محدودیت اشتراک مربوط به میزان استفاده شما در یک بازه زمانی است؛ بنابراین باید منتظر بازنشانی (reset) بمانید، سهمیه بیشتری خریداری کنید یا اگر طرح شما امکان آن را دارد، از یک فرصت بازنشانی رایگان استفاده کنید. محدودیت نرخ API مربوط به سرعت فعلی شماست و به‌محض کاهش سرعت، پس از چند ثانیه برطرف می‌شود.

سهمیه‌های طرح‌ها و اعداد مربوط به سطوح محدودیت نرخ (rate-limit tiers) به‌طور مکرر تغییر می‌کنند و درج عدد اشتباه بدتر از عدم درج آن است؛ بنابراین هیچ عددی در اینجا ذکر نشده است. برای مشاهده مقادیر مربوط به خود، از دستورات زیر استفاده کنید.

به کدام محدودیت برخورد کرده‌اید؟ پیام دقیق را بخوانید

Claude Code نام سیستم را در متنی که چاپ می‌کند ذکر می‌کند. پیش از هر تغییری، نام سیستم خود را با آن تطبیق دهید.

• You've hit your session limit · resets 3:45pm یک محدودیت اشتراک است. سهمیه چرخشی طرح شما برای این بازه زمانی به پایان رسیده است.
• You've hit your weekly limit · resets Mon 12:00am همان سیستم در بازه زمانی طولانی‌تر است.
• You've hit your Opus limit · resets 3:45pm یک محدودیت اشتراک است که فقط برای درخواست‌های Opus اعمال می‌شود. تغییر به مدلی خارج از خانواده Opus به شما امکان می‌دهد به کار خود ادامه دهید.
• You've hit your Sonnet limit · resets 3:45pm همان نوع محدودیت خانواده مدل است، اما فقط برای درخواست‌های Sonnet. تغییر به مدلی خارج از خانواده Sonnet به شما امکان می‌دهد به کار خود ادامه دهید.
• پیامی که با Fable limit reached شروع می‌شود به این معنی است که شما سهمیه هفتگی اختصاص‌یافته به مدل‌های Fable را مصرف کرده‌اید. ادامه کار با Fable از اعتبار مصرفی (usage credits) شما کسر می‌کند، بنابراین Claude Code ابتدا از شما تأیید می‌گیرد. برای ماندن در محدوده طرح خود، مدل دیگری را با /model انتخاب کنید.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. یک محدودیت نرخ API است. شما به محدودیتی برخورد کرده‌اید که برای کلید API شما، یا برای پروژه Amazon Bedrock یا Google Cloud شما پیکربندی شده است. اینکه کدام‌یک از این موارد اعمال می‌شود به نحوه احراز هویت کلاینت بستگی دارد، زیرا کلاینت Bedrock یا Vertex به‌جای سازمان Anthropic، بر اساس سهمیه پروژه ابری شما محاسبه می‌شود.
• API Error: Server is temporarily limiting requests (not your usage limit) یک محدودیت موقت (throttle) است که به سهمیه طرح شما ارتباطی ندارد. Claude Code پیش از نمایش این خط، به‌طور خودکار با استفاده از backoff تلاش مجدد می‌کند.

محدودیت‌های اشتراک: نشست، هفتگی و پنجره Opus

طرح‌های Pro، Max، Team یا Enterprise مبتنی بر جایگاه (seat-based)، شامل یک سهمیه مصرف چرخشی هستند. هنگامی که این سهمیه به پایان برسد، Claude Code درخواست‌های بعدی را تا زمان بازنشانی که در پیام نمایش داده شده است، مسدود می‌کند. دو ویژگی از این سهمیه باعث ایجاد بیشترین سردرگمی می‌شود.

• این سهمیه با چت Claude مشترک است. کاری که در claude.ai انجام می‌دهید از همان سهمیه‌ای استفاده می‌کند که کار در ترمینال از آن بهره می‌برد، بنابراین یک بعدازظهر پرکار در چت، زمان کدنویسی شما در عصر را کوتاه می‌کند. هر محیطی که با آن حساب وارد شوید از همان منبع مشترک استفاده می‌کند، بنابراین در لینوکس نسخه بتای دسکتاپ و Claude Code CLI در مجموع از یک سهمیه استفاده می‌کنند، نه از دو سهمیه مجزا.
• این سهمیه بین مدل‌ها مشترک است. محدودیت‌های نشست و هفتگی برای همه مدل‌ها یک منبع واحد هستند. استثناها، سقف‌های خانواده مدل در داخل همان منبع هستند: محدودیت‌های Opus و Sonnet، و در جایگاه‌های Max و Premium، تخصیص Fable تا سقف 50 درصد از محدودیت‌های هفتگی شما. در جایگاه‌های Pro و Standard، مدل Fable اصلاً در محدودیت‌های طرح گنجانده نشده است و از اولین درخواست، از اعتبار مصرف (usage credits) کسر می‌شود.

در Claude for Teams و Enterprise مبتنی بر جایگاه، ساختار مستندشده به صورت یک سهمیه به ازای هر جایگاه است که در یک پنجره چرخشی پنج‌ساعته و یک پنجره هفتگی بازنشانی می‌شود، با چت Claude و Cowork مشترک است و بر اساس سطح جایگاه (Standard یا Premium) تعیین می‌شود. طرح‌های Enterprise فعلی مبتنی بر مصرف، متفاوت عمل می‌کنند: هیچ سهمیه گنجانده‌شده‌ای برای تمام شدن وجود ندارد، مصرف با نرخ API محاسبه می‌شود و سقف آن، محدودیت‌های هزینه‌ای است که مدیران در سطح سازمان و برای کاربران فردی تعیین می‌کنند. در یک طرح با پشتیبانی فروش، مصرفی که توسط محدودیت هزینه متوقف شده است، در ابتدای دوره صورت‌حساب بعدی از سر گرفته می‌شود، مگر اینکه مالک ابتدا محدودیت را افزایش دهد. در یک طرح سلف‌سرویس، مصرف همچنین زمانی که موجودی اعتبار پیش‌پرداخت تمام شود متوقف می‌گردد تا زمانی که مالک اعتبار بیشتری خریداری کند. در طرح‌های Pro و Max، زمان بازنشانی چاپ‌شده در پیام و نوارهای /usage خودتان، اعداد قابل استناد هستند، نه رقمی که از یک پست وبلاگ کپی شده باشد. اگر هنوز در حال انتخاب سطح هستید، اینکه به کدام طرح Claude نیاز دارید مواردی که هر طرح محدود می‌کند را مقایسه می‌کند.

چرا تغییر مدل با استفاده از /model باعث بازیابی نشست یا سقف محدودیت هفتگی نمی‌شود

این رایج‌ترین اشتباه است و مستندات به‌صراحت به آن اشاره کرده‌اند: محدودیت‌های نشست و هفتگی بین تمام مدل‌ها مشترک هستند، بنابراین تغییر مدل باعث بازیابی دسترسی نمی‌شود. انتخاب یک مدل کوچک‌تر پس از اتمام بازهٔ نشست، فقط تعیین می‌کند که کدام مدل پاسخگو باشد. این کار میزان سهمیهٔ باقی‌مانده را تغییر نمی‌دهد، زیرا سهمیهٔ نشست و هفتگی به‌ازای هر مدل تعریف نشده است و در نتیجه، تغییر مدل چیزی را آزاد نمی‌کند.

استثناها مربوط به سقف‌های خانوادهٔ مدل‌ها هستند. اگر پیام You've hit your Opus limit یا You've hit your Sonnet limit را مشاهده کردید، آنگاه /model راهکار صحیح است. به مدلی خارج از آن خانواده تغییر وضعیت دهید و به کار خود ادامه دهید، زیرا فقط درخواست‌های آن خانواده مسدود شده بودند. محدودیت Fable در پلن‌های Max و Premium نیز به همین صورت عمل می‌کند: برای ادامهٔ کار در چارچوب پلن خود به مدل دیگری تغییر وضعیت دهید، یا با استفاده از اعتبار مصرفی (usage credits) به کار با Fable ادامه دهید. البته Fable سریع‌تر از سایر مدل‌ها از استخر هفتگی مشترک استفاده می‌کند، بنابراین تغییر مدل پس از رسیدن به محدودیت Fable، هرگز شما را از سقف کلی محدودیت هفتگی فراتر نمی‌برد.

برخورد با این محدودیت به‌عنوان یک باگ، دومین اشتباه رایج است. نصب مجدد یا احراز هویت دوباره هیچ تغییری ایجاد نمی‌کند. سهمیه زمانی بازمی‌گردد که بازهٔ زمانی بازنشانی شود، از یک بازنشانی رایگان محدودیت استفاده کنید، یا اعتبار مصرفی خریداری کنید.

هنگام مواجهه با محدودیت اشتراک چه باید کرد

1. زمان بازنشانی (reset) را بررسی کنید. پنجرهٔ نشست (session) کوتاه است. پنجرهٔ هفتگی چیزی نیست که بتوانید پشت میز خود منتظر پایان آن بمانید. در نسخهٔ Claude Code v2.1.234 یا بالاتر، /rate-limit-options می‌تواند منتظر بازنشانی بماند و وظیفهٔ متوقف‌شده را به‌طور خودکار ادامه دهد.
2. اگر محدودیت مربوط به مدل‌های Opus، Sonnet یا Fable است، /model را اجرا کرده و مدلی خارج از آن خانواده انتخاب کنید.
3. برای مشاهدهٔ محدودیت‌های طرح، نمودارهای مصرف و زمان بازنشانی آن‌ها، /usage را اجرا کنید. /cost یک نام مستعار (alias) برای همان صفحه است.
4. در claude.ai یا در Claude Desktop، به مسیر Settings > Usage بروید و بخش Resets را بررسی کنید. به طرح‌های واجد شرایط گاهی یک بازنشانی رایگان محدودیت پیشنهاد می‌شود؛ با کلیک روی "Reset for free"، محدودیت پنج‌ساعتهٔ نشست یا محدودیت هفتگی شما (هر کدام که شامل پیشنهاد باشد) بلافاصله به حالت کامل بازمی‌گردد. این دکمه در Claude Code داخل ترمینال یا IDE، و همچنین در Claude Mobile در دسترس نیست و هر پیشنهاد تاریخ انقضا دارد.
5. برای ادامهٔ کار پس از رسیدن به سقف مصرف، /usage-credits را اجرا کنید. در طرح‌های Pro و Max، این دستور تنظیمات صورت‌حساب شما را باز می‌کند. در طرح‌های Team و Enterprise، تنظیمات مصرف سازمان شما را باز کرده یا اگر دسترسی صورت‌حساب ندارید، درخواستی برای مدیران شما ارسال می‌کند.
6. اگر هر هفته به بن‌بست مشابهی می‌رسید، این طرح برای نحوهٔ کار شما مناسب نیست و راه‌های خروج از محدودیت مصرف ارزش آن را دارند که یک‌بار برای همیشه بررسی شوند، نه اینکه هر بار هنگام بازنشانی به آن‌ها فکر کنید.

/usage-credits نیازمند اشتراک claude.ai است که از طریق /login وارد شده باشد. این قابلیت با احراز هویت از طریق API key در دسترس نیست، زیرا API key فاقد سهمیهٔ طرح برای افزایش است.

اعتبار مصرف (usage credits) یک اثر جانبی دارد که بهتر است پیش از هر چیز بدانید. به‌طور پیش‌فرض، Claude Code برای مکالمهٔ اصلی شما در زمانی که در محدودهٔ مصرف مجاز اشتراک هستید، یک prompt cache یک‌ساعته در نظر می‌گیرد؛ اما به‌محض استفاده از اعتبار، آن را به پنج دقیقه کاهش می‌دهد. در نتیجه، تعداد بیشتری از نوبت‌های گفتگو به‌صورت cold شروع شده و مصرف توکن Claude Code برای همان حجم کار افزایش می‌یابد. زیرمجموعه‌ها (subagents) خارج از آن ظرف مکالمهٔ اصلی قرار دارند، بنابراین حتی در زمان استفاده از طرح اصلی نیز از پنج دقیقه زمان استفاده می‌کنند. انتخاب دستی TTL با تنظیم promptCacheTtl یا استفاده از CLAUDE_CODE_PROMPT_CACHE_TTL در نسخهٔ Claude Code v2.1.242 یا بالاتر، باعث می‌شود در زمان استفاده از اعتبار نیز طول عمر یک‌ساعته حفظ شود.

پیام‌هایی که شبیه محدودیت استفاده هستند اما نیستند

چهار خطای Claude Code گزارش می‌شوند که به نظر محدودیت استفاده می‌رسند، اما هیچ‌کدام از آن‌ها محدودیت استفاده نیستند.

• هشدار context یا auto-compact یک محدودیت استفاده نیست. /context خطی مانند Context exceeds the 200k-token limit by 94k tokens را چاپ می‌کند و پس از آن دستوری که فضا را آزاد می‌کند، نمایش می‌دهد؛ این اتفاق زمانی می‌افتد که طول گفتگو از پنجره context مدل فراتر رفته باشد. فشرده‌سازی (compacting)، تاریخچه قدیمی‌تر را خلاصه می‌کند تا فضا آزاد شود، اما این کار رایگان نیست: /compact گفتگویی را که خلاصه می‌کند می‌خواند، بنابراین فشرده‌سازی یک context بزرگ، خود یک درخواست سنگین از طرح اشتراک شما محسوب می‌شود. زمانی که به جای تداوم گفتگو، شروعی تازه می‌خواهید، /clear هزینه‌ای ندارد.
• Prompt is too long · automatic compaction failed: <the underlying error> به این معنی است که خودِ عملیات فشرده‌سازی خودکار با خطایی که نام می‌برد، شکست خورده است. /compact تا زمانی که آن خطا را برطرف نکنید، همچنان با همان خطا شکست می‌خورد.
• Credit balance is too low به این معنی است که اعتبار پیش‌پرداخت سازمان شما در Console تمام شده است، یا Claude Code در حال ارسال درخواست‌های یک مشترک از طریق یک API key در Console است؛ /status نشان می‌دهد کدام اعتبارنامه فعال است. اعتبار خود را در platform.claude.com/settings/billing افزایش دهید که قابلیت شارژ خودکار (auto-reload) را نیز ارائه می‌دهد.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context یک بررسی حق دسترسی (entitlement check) است، نه اتمام سهمیه. اگر یک نسخه [1m] از Opus 4.6 یا Sonnet 4.6 را انتخاب کرده‌اید، نسخه‌ای را انتخاب کنید که پسوند [1m] ندارد، یا CLAUDE_CODE_DISABLE_1M_CONTEXT=1 را تنظیم کنید. اگر این پیام در میانه گفتگو ظاهر شد، به این دلیل است که context از 200K توکن فراتر رفته است؛ Claude Code به‌طور خودکار آن را به زیر حد استاندارد فشرده می‌کند. مدل‌های Sonnet 5 و جدیدتر، Opus 4.7 و جدیدتر، Haiku 5.5 و مدل‌های Fable با پنجره بومی 1M اجرا می‌شوند و پسوندی برای حذف ندارند؛ آن متغیر همان چیزی است که آن‌ها را در محدودیت 200K نگه می‌دارد.

یک مورد دیگر از سمت API می‌آید. خطای 413 request_too_large یک محدودیت اندازه برای یک درخواست واحد است، نه محدودیت نرخ (rate limit).

محدودیت‌های نرخ API: شمارش واقعی خطای 429

Messages API سه مورد را به‌طور جداگانه برای هر کلاس مدل اندازه‌گیری می‌کند.

• درخواست در دقیقه (RPM)
• توکن‌های ورودی در دقیقه (ITPM)
• توکن‌های خروجی در دقیقه (OTPM)

سازمان شما همچنین دارای یک سقف هزینه است که موضوع متفاوتی محسوب می‌شود: حداکثر هزینه ماهانه برای استفاده از API. هنگامی که به سقف هزینه سطح (tier) خود می‌رسید، استفاده از API تا ماه بعد متوقف می‌شود، مگر اینکه درخواست افزایش محدودیت دهید. این وضعیت نیز با خطای 429 rate_limit_error ظاهر می‌شود، اما بدون هدر retry-after و با مقدار enforced_spend_limit_reached در error.details.error_code. هیچ حلقه تکرار مجددی (retry loop) این مشکل را حل نمی‌کند. سقف هزینه پایین‌تری که خودتان در Console تنظیم می‌کنید، به شکل متفاوتی نمایش داده می‌شود: درخواست‌ها کد وضعیت HTTP 400 invalid_request_error را با پیامی که با You have reached your specified API usage limits شروع می‌شود بازمی‌گردانند و افزایش یا حذف این محدودیت، دسترسی را بازیابی می‌کند.

چهار مکانیسم تعیین می‌کنند که چه زمانی خطای 429 رخ می‌دهد.

• محدودیت‌ها برای هر کلاس مدل هستند. این محدودیت‌ها به‌طور جداگانه برای هر مدل اعمال می‌شوند، بنابراین می‌توانید از مدل‌های مختلف تا سقف محدودیت‌های مربوط به هر کدام به‌طور همزمان استفاده کنید. برخی خانواده‌ها از یک مخزن مشترک استفاده می‌کنند: محدودیت نرخ Opus مجموع کل برای Claude Opus 4.8، Opus 4.7، Opus 4.6 و Opus 4.5 است، در حالی که Claude Sonnet 5 محدودیت خاص خود را دارد.
• ظرفیت به‌طور مداوم پر می‌شود. این API از الگوریتم token bucket استفاده می‌کند، بنابراین ظرفیت به‌جای بازنشانی در یک لحظه ثابت، به‌طور مداوم پر می‌شود. محدودیت 60 درخواست در دقیقه ممکن است به صورت یک درخواست در هر ثانیه اعمال شود، بنابراین ارسال 60 درخواست به‌صورت یکجا همچنان با شکست مواجه می‌شود.
• در اکثر مدل‌ها، فقط ورودی‌های غیرکش‌شده (uncached) در ITPM محاسبه می‌شوند. input_tokens و cache_creation_input_tokens محاسبه می‌شوند. cache_read_input_tokens در اکثر مدل‌های Claude محاسبه نمی‌شود، که Claude Haiku 3.5 استثنای مستند آن است. بنابراین، کش کردن علاوه بر تخفیف، فضای بیشتری برای محدودیت نرخ ایجاد می‌کند. در سمت خروجی، مقدار بالای max_tokens در OTPM محاسبه نمی‌شود، زیرا OTPM فقط توکن‌هایی را می‌شمارد که واقعاً تولید شده‌اند.
• محدودیت‌ها در سطح سازمان اعمال می‌شوند. می‌توان برای یک فضای کاری (workspace) محدودیت پایین‌تری تعیین کرد و محدودیت‌های کل سازمان همیشه اعمال می‌شوند، حتی اگر مجموع محدودیت‌های فضاهای کاری بیشتر باشد. محدودیتی که در یک فضای کاری بازنویسی نکرده‌اید، از سازمان به ارث می‌رسد و نامحدود باقی نمی‌ماند.

سطوح (Tiers) با نام‌های Start، Build، Scale و Custom اعداد واقعی را تعیین می‌کنند که به‌طور خودکار بر اساس تاریخچه استفاده و وضعیت حساب شما اختصاص می‌یابند. سازمان‌های جدید و آن‌هایی که تاریخچه استفاده کمی دارند ممکن است در سطح Evaluation شروع کنند که پایین‌تر از محدودیت‌های استاندارد منتشرشده است، بنابراین اولین خطای 429 ممکن است زودتر از آنچه جدول پیش‌بینی می‌کند رخ دهد. افزایش ناگهانی در استفاده، محدودیت‌های شتاب‌دهنده را فعال می‌کند که در حالی که هنوز در سطح (tier) خود هستید، خطای 429 را برمی‌گرداند؛ بنابراین ترافیک را به‌تدریج افزایش دهید. هر عدد منتشرشده یک سقف است: محدودیت‌های مستندشده، حداکثر استفاده مجاز هستند، نه حداقل‌های تضمین‌شده. برای درخواست افزایش، از گزینه "Request tier increase" در صفحه Rate limits در Claude Console استفاده کنید.

خواندن خطای 429: retry-after، هدرها و تلاش‌های مجدد SDK

هر خطای API یک ساختار یکسان را برمی‌گرداند: یک شیء تو در توی error که حاوی نوع و پیام خطا است، به علاوه یک request_id در سطح بالا.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

بقیه اطلاعات در هدرها قرار دارند.

• retry-after تعداد ثانیه‌هایی است که باید تا زمان امکان ارسال مجدد درخواست صبر کنید. تلاش‌های زودهنگام با شکست مواجه می‌شوند. همه خطاهای 429 این هدر را ندارند و خطای 429 مربوط به سقف هزینه (spend-cap) هرگز آن را شامل نمی‌شود.
• anthropic-ratelimit-requests-limit، anthropic-ratelimit-requests-remaining و anthropic-ratelimit-requests-reset بودجه درخواست شما را توصیف می‌کنند.
• anthropic-ratelimit-input-tokens-* و anthropic-ratelimit-output-tokens-* همین کار را برای ITPM و OTPM با پسوندهای مشابه limit، remaining و reset انجام می‌دهند.
• anthropic-ratelimit-tokens-* مقادیر مربوط به محدودکننده‌ترین حد مجاز که در حال حاضر اعمال شده است را نمایش می‌دهد.

هدرهای reset بر اساس فرمت زمانی RFC 3339 هستند. هدرهای مربوط به توکن‌های باقی‌مانده (remaining) به نزدیک‌ترین هزار گرد می‌شوند، بنابراین آن‌ها را به عنوان یک شاخص تقریبی در نظر بگیرید. حالت Fast دارای استخر (pool) اختصاصی و هدرهای anthropic-fast-* مخصوص به خود است. تمام آن‌ها را از هر فراخوانی موفق بخوانید:

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

هر پاسخ همچنین دارای یک هدر منحصربه‌فرد request-id است، مانند req_018EeWyXxfu5pfWkrYcMdjWG. این مقدار در بدنه خطاها به صورت request_id و در پاسخ‌های SDK پایتون و تایپ‌اسکریپت به صورت _request_id ظاهر می‌شود. هنگام تماس با پشتیبانی، این مقدار را ذکر کنید.

پیش از نوشتن یک حلقه backoff، بررسی کنید که آیا اصلاً به آن نیاز دارید یا خیر. SDKهای رسمی به‌طور خودکار خطاهای گذرا، شامل خطاهای اتصال، محدودیت نرخ (rate limits) و خطاهای سرور 5xx را با استفاده از exponential backoff (به‌طور پیش‌فرض دو بار) و با رعایت هدر retry-after در صورت وجود، مجدداً تلاش می‌کنند. هر کلاینت یک گزینه maximum-retries برای تغییر یا غیرفعال کردن این رفتار می‌پذیرد.

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 خطای overloaded تقصیر شما نیست

خطای 429 به این معناست که درخواست‌های شما بیش از حد سریع بوده است. خطای 529 overloaded_error نشان می‌دهد که API به‌طور موقت تحت فشار است و ممکن است زمانی رخ دهد که ترافیک کلی API از سوی تمامی کاربران بسیار بالا باشد. هیچ‌کدام از این موارد به کلید (key) یا کد شما مربوط نمی‌شود. با استفاده از روش exponential backoff دوباره تلاش کنید (که SDKها به‌صورت خودکار برای پاسخ‌های 5xx انجام می‌دهند) و اگر مشکل برطرف نشد، وضعیت را در status.claude.com بررسی کنید. خطای 500 api_error یک خطای داخلی است که باید به همان روش دوباره تلاش کنید؛ هیچ‌کدام از این دو مورد، محدودیت نرخ (rate limit) محسوب نمی‌شوند.

مشاهده محدودیت‌های شخصی به‌جای جدول

در یک اشتراک، /usage صفحه‌ای است که اهمیت دارد. این صفحه نوارهای میزان استفاده از طرح شما و تفکیک مواردی که آن‌ها را مصرف کرده‌اند نشان می‌دهد، و d یا w بین 24 ساعت گذشته و 7 روز گذشته جابه‌جا می‌شود. دو نکته را در نظر داشته باشید. بلوک Session میزان استفاده از توکن API را نشان می‌دهد و برای کاربران API در نظر گرفته شده است، بنابراین مشترکین می‌توانند رقم دلاری آن را نادیده بگیرند. اعداد از تاریخچه نشست محلی روی آن دستگاه می‌آیند، بنابراین استفاده از دستگاه دیگر یا از claude.ai در آن لحاظ نشده است.

در سمت API، صفحه Usage در Claude Console دو نمودار رسم می‌کند: "Rate Limit - Input Tokens" و "Rate Limit - Output Tokens". نمودار ورودی، حداکثرِ ساعتیِ توکن‌های ورودی غیرکش‌شده در هر دقیقه را در مقابل محدودیت فعلی ITPM شما رسم می‌کند و نرخ کش شما را در کنار آن نمایش می‌دهد، تا به‌جای مواجهه با محدودیت در محیط عملیاتی (production)، نزدیک‌شدن به آن را زیر نظر داشته باشید.

برای خواندن محدودیت‌های پیکربندی‌شده خود به‌صورت برنامه‌نویسی:

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

این کار به اعتبارنامه‌های Admin API نیاز دارد: یک کلید Admin API، یک توکن OAuth با اسکوپ org:admin، یا یک کلید حساب شخصی یا سرویس که محدود به یک ورک‌اسپیس نباشد. کلیدهای API ورک‌اسپیس کار نمی‌کنند. GET /v1/organizations/workspaces/{workspace_id}/rate_limits همین کار را برای هر ورک‌اسپیس انجام می‌دهد. هر دو فقط‌خواندنی هستند: برای تغییر یک محدودیت، از صفحه Rate limits در Console استفاده کنید.

استفاده از less برای مواجهه با محدودیت‌های کمتر

هر دو سیستم در لایه زیرین یک چیز را اندازه‌گیری می‌کنند، بنابراین این اهرم‌ها روی هر دو کار می‌کنند.

• در هر نوبت توکن کمتری مصرف کنید. دوره‌های کاری مداوم باعث گرم ماندن حافظه کش می‌شود و /clear بین وظایف نامرتبط هیچ هزینه‌ای ندارد. میزان مصرف توکن در Claude Code این اهرم‌ها را به‌طور کامل پوشش می‌دهد.
• تلاش را کاهش دهید. سطوح عبارتند از low، medium، high، xhigh و max. منوی /effort همچنین ultracode را ارائه می‌دهد که به‌جای کاهش هزینه، آن را افزایش می‌دهد. استدلال عمیق برای یک تغییر نام مکانیکی هیچ دستاوردی ندارد.
• پس از خطای 429، هم‌روندی (concurrency) را کاهش دهید. مقدار CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY را کم کنید و از اجرای تعداد زیادی زیر-عامل (subagent) موازی خودداری کنید. همچنین /status را اجرا کنید: یک ANTHROPIC_API_KEY سرگردان، درخواست‌ها را به‌جای اشتراک شما، از طریق یک کلید با سطح دسترسی پایین هدایت می‌کند.
• کارهای غیرتعاملی را به Message Batches API منتقل کنید. این API حجم زیادی از کارها را به‌صورت ناهمگام (asynchronous) با 50% تخفیف روی توکن‌های ورودی و خروجی و تحت محدودیت‌های نرخ (rate limits) مخصوص خود اجرا می‌کند، بنابراین یک وظیفه شبانه با نشست (session) شما رقابت نخواهد کرد.

کارهایی که داده‌ها را به درون context می‌ریزند، بیشترین فشار را حس می‌کنند: اگر در حال تحلیل سهام و اختیار معامله‌ها با داده‌های زنده بازار هستید، استخراج بخش کوچکی که هر پرسش به آن نیاز دارد، کسری از هزینه چسباندن جداول کامل قیمت‌ها و زنجیره‌ها است. کارهای انفجاری که توسط یک برنامه هدایت می‌شوند تا یک شخص، از همان ابتدا باید روی یک API key اجرا شوند. انتقال به آنجا، نحوه پرداخت و همچنین نحوه اندازه‌گیری مصرف شما را تغییر می‌دهد، زیرا Claude API هیچ سطح رایگانی ندارد. طرح‌های Max و Team شامل اعتبار ماهانه API برای اجرای برنامه‌ها و عامل‌های شخصی شما هستند، به شرطی که یک سازمان در Console متصل کنید. این اعتبارها Claude Code را پوشش نمی‌دهند و محدودیت‌های مصرف طرح شما را تغییر نمی‌دهند. اولین برنامه Claude API شما روی یک VPS مدیریت کلید و تلاش‌های مجدد (retries) را پوشش می‌دهد، و اجرای طولانی‌مدت یک عامل در صورت قطع اتصال، با نگه داشتن Claude Code در حال اجرا روی یک VPS داخل tmux زنده می‌ماند.

FAQ

چرا تغییر مدل، محدودیت استفاده من از Claude را برطرف نمی‌کند؟

زیرا محدودیت‌های نشست (session) و هفتگی در تمامی مدل‌ها مشترک هستند. این سهمیه متعلق به طرح اشتراک شماست، نه یک مدل خاص؛ بنابراین /model فقط تعیین می‌کند کدام مدل پاسخ دهد و تأثیری بر میزان سهمیه باقی‌مانده ندارد. استثناها شامل محدودیت‌های خانوادهٔ مدل‌ها هستند: You've hit your Opus limit و You've hit your Sonnet limit فقط برای همان خانواده اعمال می‌شوند و محدودیت Fable در پلن‌های Max و Premium، صرفاً استفاده از Fable را محدود می‌کند. در این موارد خاص، تغییر مدل راهکار مستند برای رفع مشکل است.

خطای 429 rate_limit_error به چه معناست و چه مدت باید منتظر بمانم؟

این خطا به این معنی است که حساب شما به محدودیت نرخ (rate limit) برای آن کلاس از مدل رسیده است: تعداد درخواست در دقیقه، توکن‌های ورودی در دقیقه یا توکن‌های خروجی در دقیقه. پاسخ دریافتی معمولاً حاوی هدر retry-after است که تعداد ثانیه‌های انتظار را مشخص می‌کند و تلاش‌های زودهنگام برای ارسال مجدد درخواست با شکست مواجه می‌شوند. SDKهای رسمی به‌طور پیش‌فرض، خطاهای نرخ و خطاهای 5xx را با الگوی exponential backoff (دو بار به صورت پیش‌فرض) بازتلاش می‌کنند و در صورت وجود هدر مذکور، آن را رعایت می‌کنند. خطای 429 که در حین فعالیت در محدودهٔ مجاز پلن شما رخ می‌دهد، نشان‌دهندهٔ محدودیت شتاب (acceleration limit) ناشی از افزایش ناگهانی ترافیک است. خطای 429 همراه با enforced_spend_limit_reached در error.details.error_code که هرگز حاوی هدر retry-after نیست، به معنای رسیدن به سقف هزینهٔ ماهانه است و انتظار کشیدن برای چند دقیقه مشکل را حل نخواهد کرد.

چگونه محدودیت‌های استفاده از Claude و زمان بازنشانی آن‌ها را مشاهده کنم؟

در Claude Code، دستور /usage را اجرا کنید تا نوار وضعیت پلن، زمان‌های بازنشانی و جزئیات مصرف را ببینید؛ /cost یک نام مستعار (alias) برای این دستور است و d یا w بین نمایش داده‌های 24 ساعت گذشته و 7 روز گذشته جابه‌جا می‌شوند. این ارقام از تاریخچهٔ نشست محلی استخراج می‌شوند، بنابراین مصرف سایر دستگاه‌ها و استفاده از claude.ai در آن‌ها لحاظ نمی‌شود. در API، کنسول (Console) محدودیت‌های نرخ شما را به صورت نمودار نمایش می‌دهد و GET /v1/organizations/rate_limits با استفاده از اعتبارنامه‌های Admin API (مانند یک کلید Admin API)، محدودیت‌های پیکربندی‌شدهٔ شما را بازمی‌گرداند.

آیا پس از رسیدن به محدودیت پلن Claude می‌توانم به کار ادامه دهم؟

گاهی اوقات. دستور /usage-credits را اجرا کنید تا در پلن‌های Pro و Max سهمیهٔ اضافی خریداری کنید، یا در پلن‌های Team و Enterprise از مدیر سیستم درخواست سهمیه کنید؛ این کار نیازمند ورود به claude.ai از طریق /login است و با احراز هویت از طریق کلید API در دسترس نیست. در غیر این صورت، منتظر زمان بازنشانی بمانید، از گزینهٔ بازنشانی محدودیت رایگان (در صورت ارائه در مسیر Settings > Usage در claude.ai یا Claude Desktop) استفاده کنید، اگر محدودیت مربوط به Opus، Sonnet یا Fable بوده مدل را تغییر دهید، یا کار خود را به یک کلید API منتقل کنید که به جای بازه‌های زمانی، بر اساس دقیقه محاسبه می‌شود.