رفع محدودیت استفاده Claude و خطای 429 API
تفاوت محدودیتهای اشتراک Claude و خطای HTTP 429 در API را بشناسید. راهنمای رفع مشکل وقتی با پیامهای محدودیت سهمیه یا Rate Limit مواجه میشوید.
محدودیتهای استفاده Claude چیست؟
محدودیتهای استفاده Claude در دو سیستم مجزا تعریف شدهاند. اولین قدم این است که تشخیص دهید کدام سیستم باعث توقف شما شده است. اشتراک Claude (شامل Pro، Max، Team، یا Enterprise) یک سهمیه استفاده متغیر (rolling usage allowance) به شما میدهد که بین مدلها و چت Claude مشترک است؛ در این حالت با پیامی مانند You've hit your session limit · resets 3:45pm متوقف میشوید. اما Claude API پارامتر دیگری را اندازهگیری میکند: سرعت ارسال درخواستها و توکنها که بر حسب دقیقه محاسبه میشود. در این حالت با خطای HTTP 429 از نوع rate_limit_error و یک هدر retry-after مواجه میشوید که تعداد ثانیههای مورد نیاز برای انتظار را اعلام میکند.
روشهای رفع این دو مشکل کاملاً متفاوت هستند. محدودیت اشتراک مربوط به میزان استفاده شما در یک بازه زمانی مشخص است؛ بنابراین باید منتظر بازنشانی (reset) بمانید یا سهمیه بیشتری خریداری کنید. محدودیت نرخ (rate limit) در API مربوط به سرعت فعلی شماست و به محض کاهش سرعت، ظرف چند ثانیه برداشته میشود.
اعداد مربوط به سهمیههای پلنها و سطوح محدودیت نرخ (rate-limit tier) مدام تغییر میکنند و ارائه عدد اشتباه بدتر از عدم ارائه عدد است، بنابراین هیچ عددی در اینجا چاپ نشده است. برای مشاهده اعداد مربوط به خود، از دستورات پایین استفاده کنید.
به کدام محدودیت برخوردید؟ پیام دقیق را بخوانید
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 اعمال میشود. در این مورد خاص، تغییر مدل میتواند کمک کند.API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.یک محدودیت نرخ (rate limit) در API است. شما به محدودیت تنظیم شده برای API key خود، یا برای پروژه Amazon Bedrock یا Google Cloud رسیدهاید.API Error: Server is temporarily limiting requests (not your usage limit)یک محدودیت موقت (throttle) است که با سهمیه طرح شما ارتباطی ندارد. Claude Code پیش از نمایش این خط، عملیات را با مکیسم backoff به صورت خودکار مجدداً تلاش میکند.
محدودیتهای اشتراک: نشست (session)، هفتگی و پنجره Opus
هر طرح اشتراک شامل یک سهمیه مصرفی متحرک (rolling usage allowance) است. وقتی این سهمیه تمام شود، Claude Code درخواستهای بعدی را تا زمان بازنشانی (reset) که در پیام نمایش داده شده است، مسدود میکند. دو ویژگی این سهمیه باعث بیشتر سوءتفاهمها میشود.
- این سهمیه با Claude chat مشترک است. کارهایی که در claude.ai انجام میدهید از همان سهمیه استفاده میکنند که در terminal استفاده میشود؛ بنابراین فعالیت زیاد در chat، زمان کدنویسی شما در عصر را کوتاه میکند.
- این سهمیه بین مدلهای مختلف مشترک است. محدودیتهای نشست (session) و هفتگی، بودجه مجزایی برای هر مدل ندارند، مگر در یک مورد استثنایی: محدودیت مدل Opus.
در طرحهای Claude for Teams و Enterprise، ساختار مستند شده به این صورت است: یک سهمیه به ازای هر کاربر (per-seat) که در یک پنجره متحرک 5 ساعره و یک پنجره هفتگی بازنشانی میشود، با Claude chat و Cowork مشترک است و بر اساس سطح کاربر (Standard یا Premium) تعیین میشود. در طرحهای Pro و Max، زمان بازنشانی چاپ شده در پیام و نمودارهای /usage شما، اعداد قابل اعتماد هستند، نه ارقامی که از یک پست وبلاگی کپی شده باشند. اگر هنوز در حال انتخاب سطح اشتراک هستید، کدام طرح Claude را نیاز دارید مقایسه میکند که هر کدام چه محدودیتهایی دارند.
چرا تغییر مدل با /model دسترسی را بازیابی نمیکند
این رایجترین اشتباه است و مستندات در این مورد صریح هستند: محدودیتهای session و weekly بین تمام مدلها مشترک هستند، بنابراین تغییر مدل باعث بازیابی دسترسی نمیشود. انتخاب یک مدل کوچکتر پس از اتمام بازه session، فقط مدل پاسخدهنده را تغییر میدهد. این کار میزان باقیمانده از quota را تغییر نمیدهد، زیرا quota هر مدل را جداگانه ذخیره نمیکند؛ بنابراین تغییر مدل چیزی برای آزاد کردن ندارد.
استثنا، محدودیت Opus است که یک سقف واقعاً مخصوص به آن مدل است. اگر پیام You've hit your Opus limit را دریافت کردید، راه حل صحیح /model است. به مدل دیگری سوئیچ کنید و به کار خود ادامه دهید، زیرا فقط درخواستهای Opus مسدود شدهاند.
در نظر گرفتن این محدودیت به عنوان یک bug، دومین اشتباه است. نصب مجدد یا احراز هویت مجدد هیچ تغییری ایجاد نمیکند. quota زمانی بازمیگردد که window ریست شود، یا زمانی که usage credits خریداری کنید.
اقدامات لازم در صورت رسیدن به محدودیت اشتراک
- زمان بازنشانی (reset time) را بررسی کنید. بازه زمانی یک session کوتاه است. بازه زمانی هفتگی به گونهای نیست که نیاز باشد پشت میز منتظر بمانید.
- اگر محدودیت مربوط به مدل Opus است، دستور
/modelرا اجرا کرده و مدل دیگری را انتخاب کنید. - دستور
/usageرا اجرا کنید تا محدودیتهای طرح، میزان مصرف باقیمانده و زمان بازنشانی آنها را مشاهده کنید. دستور/costنیز مستقیماً همان صفحه را باز میکند. - برای ادامه کار پس از عبور از سقف مجاز، دستور
/usage-creditsرا اجرا کنید. در طرحهای Pro و Max، این دستور تنظیمات پرداخت (billing settings) را باز میکند. در طرحهای Team و Enterprise، تنظیمات میزان مصرف سازمان را باز میکند؛ اگر دسترسی به پرداخت ندارید، درخواستی برای مدیران (admins) ارسال میشود. - اگر هر هفته با همین محدودیت مواجه میشوید، طرح فعلی با حجم کاری شما همخوانی ندارد.
دستور /usage-credits نیازمند اشتراک claude.ai است که از طریق /login وارد شده باشد. این دستور با استفاده از API key در دسترس نیست، زیرا API key سهمیه طرحی برای افزایش ندارد.
اعتبار مصرف (Usage credits) یک اثر جانبی مهم دارد. مدت زمان ماندگاری حافظه موقت پرامپت (prompt cache) در حالت اشتراک 1 ساعت است، اما پس از استفاده از اعتبارها، این مدت به 5 دقیقه کاهش مییابد؛ بنابراین تعداد دفعات بیشتری با حالت cold شروع میشود و Claude Code token usage برای انجام همان حجم کار، افزایش مییابد.
پیامهایی که شبیه محدودیتهای استفاده هستند اما نیستند
چهار خطای Claude Code به عنوان محدودیت استفاده (usage limits) گزارش میشوند، در حالی که هیچکدام از آنها محدودیت استفاده نیستند.
- هشدار context یا auto-compact محدودیت استفاده نیست. وقتی حجم گفتگو از context window مدل فراتر برود،
/contextخطایی مانندContext exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.چاپ میکند. تاریخچه قدیمی برای آزاد کردن فضا خلاصه (summarize) میشود و سهمیه طرح شما تغییری نمیکند. Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.به این معناست که خودِ/compactشکست خورده است، زیرا فضای context آزاد کافی برای نگه داشتن خلاصهای که باید تولید کند، وجود ندارد.Credit balance is too lowبه این معناست که سازمان شما در Console اعتبار پیشپرداخت خود را تمام کرده است. در مسیر platform.claude.com/settings/billing اعتبار اضافه کنید؛ این بخش قابلیت auto-reload را نیز دارد.API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard contextیک بررسی سطح دسترسی (entitlement check) است، نه اتمام سهمیه (quota). مدل بدون پسوند[1m]را انتخاب کنید، یاCLAUDE_CODE_DISABLE_1M_CONTEXT=1را تنظیم کنید.
یک مورد دیگر از سمت API میآید. خطای 413 request_too_large محدودیت اندازه در یک درخواست واحد است، نه محدودیت نرخ درخواست (rate limit).
API rate limits: معنای واقعی خطای 429 چیست
Messages API سه معیار را به صورت مجزا برای هر کلاس مدل اندازهگیری میکند:
- requests per minute (RPM)
- input tokens per minute (ITPM)
- output tokens per minute (OTPM)
سازمان شما دارای یک محدودیت هزینه (spend limit) نیز هست که موضوعی متفاوت است: حداکثر هزینه ماهانه برای استفاده از API. وقتی به سقف هزینه سطح (tier) خود برسید، استفاده از API متوقف میشود تا ماه بعد؛ مگر اینکه درخواست افزایش محدودیت بدهید. هیچ حلقه تکرار (retry loop) برای حل این مشکل وجود ندارد.
چهار مکانیسم تعیین میکنند که چه زمانی خطای 429 رخ دهد:
- محدودیتها برای هر کلاس مدل اعمال میشوند. این محدودیتها برای هر مدل به صورت جداگانه اعمال میشوند، بنابراین میتوانید از مدلهای مختلف تا رسیدن به محدودیتهای مربوطه، همزمان استفاده کنید. برخی خانوادهها از یک ظرف مشترک استفاده میکنند: محدودیت نرخ Opus مجموعاً برای Claude Opus 4.8، Opus 4.7، Opus 4.6 و Opus 4.5 است، در حالی که Claude Sonnet 5 محدودیت مخصوص به خود را دارد.
- ظرفیت به صورت مداوم بازنشانی میشود. این API از الگوریتم token bucket استفاده میکند، بنابراین ظرفیت به جای بازنشانی در یک لحظه مشخص، به صورت مداوم پر میشود. محدودیت 60 requests per minute ممکن است به صورت یک request per second اعمال شود؛ بنابراین اگر 60 request را همزمان ارسال کنید، باز هم با خطا مواجه خواهید شد.
- در اکثر مدلها، فقط ورودیهای بدون کش (uncached input) در ITPM محاسبه میشوند.
input_tokensوcache_creation_input_tokensمحاسبه میشوند. در اکثر مدلهای Claude،cache_read_input_tokensمحاسبه نمیشود، مگر در مورد استثنای مستند شده Claude Haiku 3.5. بنابراین، استفاده از Caching علاوه بر تخفیف، باعث افزایش فضای خالی در محدودیت نرخ (rate-limit headroom) نیز میشود. در بخش خروجی، یکmax_tokensبالا در OTPM محاسبه نمیشود، زیرا OTPM فقط توکنهای واقعاً تولید شده را میشمارد. - محدودیتها در سطح سازمان اعمال میشوند. ممکن است برای یک workspace محدودیت کمتری در نظر گرفته شود، اما محدودیتهای سطح سازمان همیشه اعمال میشوند، حتی اگر مجموع محدودیتهای workspace بیشتر باشد. اگر محدودیتی را در یک workspace بازنویسی (override) نکنید، این محدودیت از سازمان ارثبری میشود و بدون محدودیت باقی نمیماند.
سطوح Start، Build، Scale و Custom اعداد واقعی را تعیین میکنند که به صورت خودکار بر اساس تاریخچه استفاده و وضعیت حساب شما اختصاص داده میشوند. سازمانهای جدید ممکن است با محدودیتهای کمتر از مقادیر منتشر شده شروع کنند، بنابراین اولین خطای 429 ممکن است زودتر از آنچه در جداول پیشبینی شده، رخ دهد. افزایش ناگهانی در میزان استفاده، باعث فعال شدن محدودیتهای شتاب (acceleration limits) میشود که در حالی که هنوز در سطح (tier) خود هستید، خطای 429 برمیگرداند؛ بنابراین ترافیک را به تدریج افزایش دهید. تمام اعداد منتشر شده، سقف هستند: محدودیتهای مستند شده، حداکثر میزان استفاده مجاز هستند، نه حداقلهای تضمین شده. برای درخواست مقدار بیشتر، از کنترل "Request rate limit increase" در صفحه 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تعداد ثانیههایی است که باید صبر کنید تا بتوانید درخواست را مجدداً ارسال کنید. تلاشهای زودتر از موعد با شکست مواجه میشوند.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 token به نزدیکترین عدد هزار گرد شدهاند، بنابراین آنها را به عنوان یک شاخص تقریبی در نظر بگیرید. حالت Fast mode دارای استخر اختصاصی و هدرهای 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های Python و TypeScript به صورت _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_error تقصیر شما نیست
خطای 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 token را نشان میدهد و مخصوص کاربران API است؛ بنابراین مشترکین عادی میتوانند از عدد دلاری آن صرفنظر کنند. این اعداد از تاریخچه session محلی در آن دستگاه خوانده میشوند، بنابراین میزان مصرف از دستگاههای دیگر یا از claude.ai در اینجا نمایش داده نمیشود.
در بخش API، صفحه Usage در Claude Console دو نمودار رسم میکند: "Rate Limit - Input Tokens" و "Rate Limit - Output Tokens". نمودار input، حداکثر میزان توکنهای ورودی بدون کش (uncached) در هر دقیقه را در برابر محدودیت فعلی ITPM شما رسم میکند و نرخ کش (cache rate) را نیز در کنار آن نشان میدهد؛ به این ترتیب میتوانید قبل از رسیدن به محدودیت در محیط 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 key نیاز دارد و GET /v1/organizations/workspaces/{workspace_id}/rate_limits نیز همین کار را برای هر workspace انجام میدهد. هر دو حالت فقط خواندنی (read-only) هستند: برای تغییر یک محدودیت، از تب Limits در Console استفاده کنید.
استفاده از less برای کاهش محدودیتها
هر دو سیستم در لایههای زیرین یک پارامتر را اندازهگیری میکنند، بنابراین این روشها روی هر دو سیستم عمل میکنند.
- مصرف توکن کمتر در هر مرحله. فعالیتهای مداوم باعث گرم ماندن cache میشوند و
/clearبین وظایف بیارتباط، هزینهای ندارد. Claude Code token usage تمام این موارد را پوشش میدهد. - کاهش میزان تلاش (effort). سطوح موجود عبارتند از
low،medium،high،xhighوmax. منوی/effortهمچنین گزینهultracodeرا ارائه میدهد که به جای کاهش، میزان مصرف را افزایش میدهد. استفاده از استدلال عمیق (deep reasoning) برای تغییر نام یک فایل مکانیکی، فایدهای ندارد. - کاهش همزمانی (concurrency) پس از دریافت خطای 429. مقدار
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYرا کاهش دهید و از اجرای همزمان چندین subagent خودداری کنید. همچنین/statusرا اجرا کنید: یکANTHROPIC_API_KEYسرگردان، درخواستها را به جای اشتراک شما، از طریق یک key با سطح پایین هدایت میکند. - انتقال کارهای غیرتعاملی به Message Batches API. این API حجم بالای درخواستها را به صورت ناهمگام (asynchronous) با 50% تخفیف در توکنهای ورودی و خروجی، تحت محدودیتهای نرخ (rate limits) مخصوص خود اجرا میکند؛ بنابراین یک job شبانه، با session شما رقابت نخواهد کرد.
کارهای متناوب (bursty) که توسط یک برنامه هدایت میشوند و نه یک شخص، از ابتدا باید از یک API key استفاده کنند. Your first Claude API app on a VPS نحوه مدیریت key و تلاش مجدد (retries) را پوشش میدهد؛ همچنین با Claude Code running on a VPS inside tmux، یک اجرای طولانی توسط agent در صورت قطع اتصال، پایداری خود را حفظ میکند.
FAQ
چرا تغییر مدل، محدودیت استفاده من از Claude را برطرف نمیکند؟
چون محدودیتهای نشست (session) و هفتگی بین تمام مدلها مشترک هستند. سهمیه متعلق به طرح کاربری است، نه یک مدل خاص؛ بنابراین /model فقط مدل پاسخدهنده را تغییر میدهد و میزان سهمیه باقیمانده را تغییر نمیدهد. تنها استثنا You've hit your Opus limit است که فقط برای درخواستهای Opus اعمال میشود. در آن حالت، تغییر مدل راهکار مستند شده است.
خطای 429 rate_limit_error به چه معناست و چقدر باید منتظر بمانم؟
این خطا به این معناست که حساب شما به محدودیت نرخ (rate limit) برای آن کلاس مدل رسیده است: درخواست در دقیقه، توکن ورودی در دقیقه، یا توکن خروجی در دقیقه. پاسخ شامل یک هدر retry-after شامل تعداد ثانیههای انتظار است و تلاشهای مجددِ زودهنگام با شکست مواجه میشوند. SDKهای رسمی با رعایت آن هدر، محدودیتهای نرخ و خطاهای 5xx را با استفاده از روش exponential backoff (دو بار به صورت پیشفرض) مجدداً تلاش میکنند. اگر در حالی که هنوز در محدوده طرح خود هستید با خطای 429 مواجه شوید، نشاندهنده محدودیت شتاب (acceleration limit) ناشی از افزایش ناگهانی درخواستها است.
چگونه محدودیتهای استفاده از Claude و زمان بازنشانی آنها را ببینم؟
در Claude Code، دستور /usage را برای مشاهده نمودارهای طرح، زمانهای بازنشانی و جزئیات استفاده اجرا کنید؛ دستور /cost یک نام مستعار (alias) است و دستورات d یا w بین بازه 24 ساعت گذشته و 7 روز گذشته سوئیچ میکنند. این ارقام از تاریخچه نشست محلی استخراج میشوند، بنابراین شامل استفاده از دستگاههای دیگر و سایت claude.ai نمیشوند. در API، بخش Console محدودیتهای نرخ شما را نمودار میکند و دستور GET /v1/organizations/rate_limits با استفاده از یک Admin API key، محدودیتهای پیکربندی شده شما را برمیگرداند.
آیا میتوانم پس از رسیدن به محدودیت طرح Claude به کار خود ادامه دهم؟
در برخی موارد ممکن است. برای خرید سهمیه اضافی در طرحهای Pro و Max، دستور /usage-credits را اجرا کنید؛ یا برای طرحهای Team و Enterprise، درخواست خود را از مدیر (admin) بخواهید؛ این کار نیاز به ورود به claude.ai از طریق /login دارد و با احراز هویت API key امکانپذیر نیست. در غیر این صورت، منتظر زمان بازنشانی بمانید، اگر محدودیت مربوط به Opus بود مدل را تغییر دهید، یا کار را به یک API key منتقل کنید که به جای بازه زمانی، بر اساس میزان استفاده در دقیقه محاسبه میکند.