مرجع کدهای خطا

مرجعی برای کدهای خطای API در QCode.cc: معنای 400/401/402/403/429/500/502/503/529، علت‌های معمول و راه‌حل‌های آزموده‌شده، شامل INSUFFICIENT_BALANCE

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

این سند اطلاعات مفصلی درباره کدهای خطای گوناگونی که ممکن است هنگام استفاده از Claude Code با آن‌ها روبه‌رو شوید و راه‌حل‌هایشان ارائه می‌کند.

مرجع سریع کدهای خطا¶

429 - درخواست‌های بیش از حد¶

یکی از رایج‌ترین خطاها که نشان‌دهنده درخواست‌های بیش از حد در یک بازه کوتاه است.

پیام خطا¶

Error: 429 Too Many Requests
Rate limit exceeded. Please slow down your requests.

علت‌های رایج¶

1. درخواست‌های بیش از حد مکرر: ارسال چندین درخواست به‌صورت پشت‌سرهم و سریع

2. درخواست‌های هم‌زمان بیش از حد: اجرای هم‌زمان چند نمونه از Claude Code

3. رسیدن به سقف توکن: مصرف بیش از حد توکن‌ها در زمان کوتاه

اتمام سهمیه خطای 429 نیست: وقتی سهمیه روزانه، کلی یا هفتگی تمام شود، پاسخ 402 (insufficient_quota) است — اتمام سهمیه را در همین صفحه ببینید.

راه‌حل‌ها¶

اقدامات فوری:

# Wait 30-60 seconds before retrying
sleep 60 && claude "your question"

راه‌حل‌های بلندمدت:

1. فراوانی درخواست‌ها را کاهش دهید و از ارسال پشت‌سرهم و سریع خودداری کنید

2. از دستور /compact برای فشرده‌سازی زمینه استفاده کنید

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

مزیت QCode.cc: توزیع بار حرفه‌ای برای پخش فشار درخواست‌ها که به‌طور مؤثر خطاهای 429 را کاهش می‌دهد.

502 - دروازه نامعتبر¶

نشان می‌دهد که دروازه یا سرور پروکسی پاسخ نامعتبری از بک‌اند دریافت کرده است.

پیام خطا¶

Error: 502 Bad Gateway
The server received an invalid response from the upstream server.

علت‌های رایج¶

1. بک‌اند موقتاً در دسترس نیست: مشکل در سرور API Anthropic

2. قطع اتصال شبکه: اتصال در حین درخواست قطع شده است

3. مشکل سرور پروکسی: خرابی گره میانی

4. اتمام مهلت درخواست: زمان پاسخ از محدودیت دروازه فراتر رفته است

راه‌حل‌ها¶

اقدامات فوری:

# Check network connection
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Wait and retry
sleep 30 && claude "your question"

راه‌حل‌های بلندمدت:

1. پایداری شبکه محلی را بررسی کنید

2. تغییر محیط شبکه را امتحان کنید

3. از VPN یا شبکه پایدارتر استفاده کنید

4. اگر مشکل ادامه یافت با پشتیبانی تماس بگیرید

مزیت QCode.cc: استقرار چندمنطقه‌ای، شتاب‌دهی CDN و جابه‌جایی خودکار در صورت خرابی.

401 - احراز هویت نشده¶

کلید API نامعتبر است یا احراز هویت معتبر وجود ندارد.

پیام خطا¶

Error: 401 Unauthorized
Invalid API key or authentication token.

علل رایج¶

1. کلید API نادرست: هنگام کپی، کاراکترها جا افتاده‌اند یا فاصله اضافی وجود دارد

2. کلید API منقضی‌شده: اشتراک منقضی شده است

3. کلید API غیرفعال‌شده: به‌دلیل نقض سیاست مسدود شده است

4. متغیر محیطی تنظیم نشده: ANTHROPIC_AUTH_TOKEN پیکربندی نشده است

راه‌حل‌ها¶

کلید API را بررسی کنید:

# Check environment variable
echo $ANTHROPIC_AUTH_TOKEN

# Confirm correct format (starts with cr_)
# Correct example: cr_xxxxxxxxxxxxxxxxxxxx

مراحل:

1. به داشبورد QCode.cc وارد شوید تا وضعیت کلید API را بررسی کنید

2. تأیید کنید که اشتراک فعال است

3. اگر مسدود شده است، با پشتیبانی تماس بگیرید

402 - پرداخت لازم است¶

یک 402 می‌تواند دو معنای متفاوت داشته باشد؛ ابتدا بدنه پاسخ را بررسی کنید. اگر error.type برابر insufficient_quota باشد، سهمیه شما تمام شده است (بخش سهمیه تمام‌شده را ببینید)؛ در غیر این صورت، سرویس مدل موقتاً درخواست را رد می‌کند (بخش سرویس موقتاً درخواست را رد می‌کند را ببینید).

سهمیه تمام‌شده (insufficient_quota)¶

پاسخ HTTP 402 با error.type = insufficient_quota است؛ code به شما می‌گوید کدام سهمیه تمام شده است:

نمونه بدنه پاسخ (سهمیه کل تمام شده):

{
  "error": {
    "type": "insufficient_quota",
    "message": "...",
    "code": "total_cost_limit_exceeded"
  },
  "currentCost": 100.42,
  "costLimit": 100
}

متن message یک اعلان کوتاه به زبان چینی است؛ بنابراین به type و code تکیه کنید. مبلغ داخل پرانتز آن (برای مثال $100) سقف آن سهمیه است — برای سهمیه کل، سقف تجمعی است — نه مقدار باقی‌مانده.

این نوع 402 با ارسال دوباره از بین نمی‌رود؛ حلقه تلاش مجدد ننویسید؛ در عوض سهمیه را مطابق جدول بازیابی کنید.

کلید منقضی‌شده 401 برمی‌گرداند، نه 402 ({"error":"Invalid API key","message":"API key has expired"}) — بخش 401 بالا را ببینید.

سرویس موقتاً درخواست را رد می‌کند¶

وقتی بدنه پاسخ insufficient_quota ندارد، زنجیره سرویس مدل این درخواست را رد کرده است. این معمولاً مشکل کلید یا پیکربندی شما نیست — درخواست‌های هم‌زمان از همان کلید به مدل‌های دیگر معمولاً موفق می‌شوند.

آنچه می‌بینید¶

Error: 402 Payment Required

در Claude Code معمولاً به این صورت دیده می‌شود که درخواست به‌سادگی و بدون محتوای پاسخ شکست می‌خورد؛ از یک اسکریپت یا SDK پاسخ HTTP 402 دریافت می‌کنید.

علل رایج¶

1. سرویس مدل موقتاً در دسترس نیست: این نوع 402 از زنجیره سرویس می‌آید و دروازه QCode وضعیت را همان‌طور که هست منتقل می‌کند

2. متمرکز بر یک مدل: در هر لحظه ممکن است یک مدل نرخ بالای 402 را تجربه کند در حالی که مدل‌های دیگر کاملاً بی‌مشکل هستند

3. به دامنه نقطه پایانی بستگی دارد: دامنه‌های مختلف از مسیرهای سرویس متفاوتی عبور می‌کنند و احتمال برخورد با 402 می‌تواند تفاوت چشمگیری داشته باشد

4. به موجودی شما مرتبط نیست: این نوع 402 به‌دلیل تمام‌شدن موجودی یا سهمیه پلن ایجاد نمی‌شود؛ 402 مربوط به سهمیه حاوی insufficient_quota است، بخش سهمیه تمام‌شده بالا را ببینید

چه کاری انجام دهید¶

1. مدل را عوض کنید (مؤثرترین راه)

# Switch inside a session
/model sonnet

# Or specify at launch
claude --model claude-sonnet-5

2. دامنه نقطه پایانی را عوض کنید

# Mainland China
export ANTHROPIC_BASE_URL=https://asia.qcode.cc/api

# Global (Route 53 picks the nearest node)
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api

هر سه دامنه یک کلید را می‌پذیرند، بنابراین تغییر دامنه به تغییر پیکربندی دیگری نیاز ندارد. بخش نقاط پایانی و قالب‌های API را ببینید.

3. حلقه تلاش مجدد فشرده ننویسید

402 با ارسال فوری دوباره از بین نمی‌رود؛ فشار آوردن فقط وضعیت را بدتر می‌کند. از عقب‌نشینی نمایی استفاده کنید یا صرفاً مدل را عوض کنید — بخش «بهترین شیوه‌های مدیریت خطا» در همین صفحه را ببینید.

4. اگر ادامه داشت، با پشتیبانی تماس بگیرید

زمان رخداد، شناسه مدل و دامنه نقطه پایانی را ذکر کنید و از طریق گفتگوی زنده یا hi@qcode.cc با ما در تماس باشید.

INSUFFICIENT_BALANCE / Insufficient account balance¶

برخی پاسخ‌های 402/403 حاوی JSON مانند "code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance" هستند. این به معنی تمام‌شدن موجودی QCode شما نیست. این یک وضعیت موقت در جایی از زنجیره سرویس است که بدون تغییر منتقل می‌شود — نامرتبط با حساب کاربری شما. وقتی سهمیه خودتان تمام شود، بدنه پاسخ insufficient_quota را همراه با کد *_cost_limit_exceeded دارد (بخش سهمیه تمام‌شده بالا را ببینید).

چه کاری انجام دهید: صبر کنید و دوباره تلاش کنید / مدل را عوض کنید / دامنه دسترسی را عوض کنید (مراحل ①–③ بالا همگی اعمال می‌شوند)؛ اگر ادامه داشت، با ذکر شناسه درخواست با پشتیبانی تماس بگیرید. چک‌لیست کامل: راهنمای عیب‌یابی.

403 - ممنوع¶

درخواست توسط سرور رد می‌شود، معمولاً به دلیل مجوزهای ناکافی.

پیام خطا¶

Error: 403 Forbidden
You don't have permission to access this resource.

دلایل رایج¶

1. نقطه پایانی API نادرست: استفاده از نشانی API نادرست

2. مجوزهای ناکافی: پلن فعلی از این ویژگی پشتیبانی نمی‌کند

3. محدودیت‌های منطقه‌ای: برخی ویژگی‌ها در مناطق خاص در دسترس نیستند

4. مشکلات وضعیت حساب کاربری: حساب کاربری محدود شده است

راه‌حل‌ها¶

# Confirm API endpoint is correct
echo $ANTHROPIC_BASE_URL
# Should be: https://api.qcode.cc/api

1. پیکربندی نقطه پایانی API را بررسی کنید

2. تأیید کنید که پلن شامل ویژگی‌های مورد نیاز است

3. برای تأیید مجوزها با پشتیبانی تماس بگیرید

INSUFFICIENT_BALANCE (هنگامی که در یک 403 ظاهر می‌شود)¶

اگر بدنه پاسخ 403 ممنوع شامل INSUFFICIENT_BALANCE / Insufficient account balance باشد، این نیز معمولاً یک وضعیت موقت در بک‌اند است که عیناً منتقل می‌شود — نه محدود شدن حساب کاربری شما. آن را مانند زیربخش هم‌نام در بخش 402 مدیریت کنید؛ برای ترتیب کامل به راهنمای عیب‌یابی مراجعه کنید.

400 - درخواست نامعتبر¶

قالب درخواست نادرست است یا پارامترها نامعتبر هستند.

پیام خطا¶

Error: 400 Bad Request
The request was malformed or contained invalid parameters.

دلایل رایج¶

1. درخواست با قالب نادرست: قالب JSON نادرست

2. نبود پارامترها: پارامترهای مورد نیاز ارائه نشده‌اند

3. مقادیر نامعتبر: مقادیر پارامترها خارج از محدوده مجاز هستند

4. مشکلات کدگذاری: کاراکترهای خاص به‌درستی کدگذاری نشده‌اند

راه‌حل‌ها¶

# Check for special characters in input
# Ensure request content is properly formatted
claude -p "simple test"

1. ورودی را ساده کنید و کاراکترهای خاص را حذف کنید

2. اطمینان حاصل کنید که مسیرهای فایل از کدگذاری درست استفاده می‌کنند

3. قالب پارامترهای دستور را بررسی کنید

500 - خطای داخلی سرور¶

سرور با وضعیت غیرمنتظره‌ای روبه‌رو شد که از تکمیل درخواست جلوگیری کرد.

پیام خطا¶

Error: 500 Internal Server Error
An unexpected error occurred on the server.

دلایل رایج¶

1. باگ سمت سرور: مشکل در کد سرور API

2. اتمام منابع: منابع سرور موقتاً تمام شده‌اند

3. خطای پیکربندی: پیکربندی نادرست سرور

راه‌حل‌ها¶

# Wait and retry
sleep 60 && claude "your question"

# Use verbose mode for more info
claude --verbose

1. چند دقیقه صبر کنید و دوباره تلاش کنید

2. وضعیت سرویس QCode.cc را بررسی کنید

3. اگر مشکل ادامه داشت، با جزئیات خطا با پشتیبانی تماس بگیرید

E015 - سرریز زمینه مکالمه¶

زمانی فعال می‌شود که زمینه مکالمه به محدودیت ظرفیت مدل (حدود 95%) نزدیک شود. QCode.cc این خطا را در قالب پاسخ 429 قرار می‌دهد تا تلاش مجدد فعال شود:

429 {"error":{"code":"E015","message":"Internal server error"},"status":500}

راه‌حل: بخش «جلوگیری از سرریز جلسه طولانی» را در مدیریت زمینه ببینید.

503 - سرویس در دسترس نیست¶

سرور موقتاً نمی‌تواند به درخواست‌ها رسیدگی کند، معمولاً به‌دلیل اضافه‌بار یا نگهداری.

پیام خطا¶

Error: 503 Service Unavailable
The service is temporarily unavailable. Please try again later.

علل رایج¶

1. اضافه‌بار سرور: حجم درخواست‌ها از ظرفیت فراتر می‌رود

2. نگهداری برنامه‌ریزی‌شده: سرور در حال نگهداری است

3. تمام‌شدن منابع: منابع سرور موقتاً کافی نیست

راه‌حل‌ها¶

# Use exponential backoff retry
for i in 1 2 4 8 16; do
  claude "your question" && break
  echo "Retrying, waiting ${i} seconds..."
  sleep $i
done

1. چند دقیقه صبر کنید و دوباره تلاش کنید

2. از راهبرد تلاش مجدد با عقب‌نشینی نمایی استفاده کنید

3. اعلان‌های وضعیت سرویس را بررسی کنید

529 - اضافه‌بار¶

کد خطای مخصوص Claude API که نشان‌دهنده اضافه‌بار سرویس API است.

پیام خطا¶

Error: 529 Overloaded
The API is temporarily overloaded. Please try again later.

علل رایج¶

1. جهش جهانی مصرف: جهش ناگهانی کاربران جهانی سرویس Claude

2. ساعات اوج مصرف: تمرکز درخواست‌ها در ساعات کاری

3. رویدادهای محبوب: برخی رویدادها باعث جهش مصرف می‌شوند

راه‌حل‌ها¶

# Retry later
sleep 120 && claude "your question"

1. 2-5 دقیقه صبر کنید و دوباره تلاش کنید

2. از ساعات اوج مصرف (ساعات کاری ایالات متحده) پرهیز کنید

3. از /compact برای کاهش مصرف توکن استفاده کنید

مزیت QCode.cc: سازوکارهای توزیع بار فشار اضافه‌بار را به‌طور مؤثر توزیع می‌کنند.

پایان مهلت اتصال¶

درخواست در زمان مشخص‌شده کامل نشد.

پیام خطا¶

Error: Connection timed out
The request timed out while waiting for a response.

علل رایج¶

1. شبکه ناپایدار: کیفیت اتصال شبکه ضعیف است

2. درخواست بسیار بزرگ: توکن‌های زمینه بیش از حد زیاد هستند

3. وظیفه بیش از حد پیچیده: زمان پردازش هوش مصنوعی بیش از حد طولانی است

4. پاسخ کند سرور: بار بالای سرور

راه‌حل‌ها¶

# Test network connection
ping api.qcode.cc

# Use compact mode to reduce context
/compact

1. پایداری اتصال شبکه را بررسی کنید

2. از /compact برای فشرده‌سازی زمینه استفاده کنید

3. وظایف پیچیده را به وظایف ساده‌تر تقسیم کنید

4. محیط شبکه پایدارتری را امتحان کنید

خطاهای سرور MCP¶

خطاهایی که می‌توانند از پیکربندی یا زمان اجرای سرور MCP بیایند.

نشانه‌ها¶

MCP server "xxx" failed to start
MCP connection timed out
MCP tool execution failed

علل رایج¶

1. دستور سرور اشتباه: نام بسته npx دارای اشتباه تایپی است یا نصب نشده است

2. متغیرهای محیطی جاافتاده: توکنی که سرور MCP به آن نیاز دارد تنظیم نشده است

3. اتمام مهلت: راه‌اندازی یا اجرای سرور بیش از حد طول می‌کشد

4. مجوزهای ناکافی: دسترسی به سیستم فایل / پایگاه داده رد می‌شود

راه‌حل‌ها¶

# Check server status with /mcp
/mcp

# Diagnose configuration issues with /doctor
/doctor

# Manually test whether the MCP server can start
npx -y @modelcontextprotocol/server-filesystem /tmp

1. وضعیت اتصال را با /mcp بررسی کنید

2. تشخیص خودکار را با /doctor اجرا کنید

3. قالب ~/.claude/settings.json یا .mcp.json را بررسی کنید

4. مطمئن شوید متغیرهای محیطی لازم تنظیم شده‌اند ($GITHUB_TOKEN و غیره)

5. مهلت‌ها را با متغیرهای محیطی MCP_TIMEOUT و MCP_TOOL_TIMEOUT افزایش دهید

مراحل کلی عیب‌یابی¶

هنگام روبه‌رو شدن با هر خطا، این مراحل را دنبال کنید:

0. اجرای تشخیص خودکار¶

# Claude Code's built-in diagnostic tool
/doctor

این ابزار به‌طور خودکار مشکلات رایج پیکربندی را بررسی می‌کند: متغیرهای محیطی، اتصال API، وضعیت سرور MCP و موارد دیگر.

1. بررسی اتصال شبکه¶

# Test API endpoint connectivity
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Test DNS resolution
nslookup api.qcode.cc

2. بررسی متغیرهای محیطی¶

# Check all relevant environment variables
echo "BASE_URL: $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:0:10}..."

3. فعال‌سازی گزارش‌گیری تفصیلی¶

# Use verbose mode for detailed info
claude --verbose

# Or set debug mode
DEBUG=true claude

4. آزمایش یک درخواست ساده¶

# Send simple test request
claude -p "say hello"

5. بررسی وضعیت سرویس¶

برای اطلاعیه‌های وضعیت سرویس به QCode.cc مراجعه کنید.

بهترین شیوه‌های مدیریت خطا¶

پیاده‌سازی سازوکار تلاش مجدد¶

# Simple retry script
retry_claude() {
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    claude "$@" && return 0
    echo "Attempt $attempt failed, retrying..."
    sleep $((attempt * 2))
    ((attempt++))
  done

  echo "All attempts failed"
  return 1
}

پایش مصرف¶

مصرف API را به‌طور منظم بررسی کنید تا از سهمیه فراتر نروید:

1. وارد داشبورد QCode.cc شوید

2. آمار مصرف را ببینید

3. هشدارهای مصرف را تنظیم کنید

بهینه‌سازی درخواست‌ها¶

1. کاهش زمینه: به‌طور منظم از /compact یا /clear استفاده کنید

2. پردازش دسته‌ای: کارهای بزرگ را به کارهای کوچک‌تر تقسیم کنید

3. پرهیز از تکرار: نتایج پرتکرار را کش کنید

دریافت کمک¶

اگر راه‌حل‌های بالا مشکل شما را برطرف نکرد، با پشتیبانی QCode.cc تماس بگیرید:

• چت زنده: گوشه پایین‌راست وب‌سایت

• زمان پاسخ: 1-2 ساعت در ساعات کاری

• ساعات پشتیبانی: 10:00–22:00 هر روز

هنگام تماس با پشتیبانی، لطفاً این موارد را ارائه دهید:

1. پیام خطای کامل

2. دستوری که اجرا شده است

3. زمان وقوع

4. پیشوند کلید API (هرگز کلید کامل را به اشتراک نگذارید)

سازمانی ←