مرجع رموز الأخطاء

مرجع لرموز أخطاء QCode.cc API: دلالات 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. بلوغ حد token: استهلاك عدد كبير جدًا من token في وقت قصير

نفاد الحصة ليس خطأ 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. الواجهة الخلفية غير متاحة مؤقتًا: مشكلات في خادم Anthropic API

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 - التحميل الزائد¶

رمز خطأ خاص بـ API Claude يشير إلى التحميل الزائد على خدمة 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 لتقليل استخدام token

ميزة QCode.cc: آليات توزيع الحمل توزّع ضغط التحميل الزائد بفعالية.

مهلة الاتصال¶

فشل الطلب في الاكتمال ضمن الوقت المحدد.

رسالة الخطأ¶

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

الأسباب الشائعة¶

1. شبكة غير مستقرة: جودة اتصال الشبكة ضعيفة

2. الطلب كبير جدًا: عدد tokens السياق كبير جدًا

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. متغيرات بيئة مفقودة: token الذي يحتاجه خادم 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 (لا تشارك المفتاح كاملًا أبدًا)

المؤسسات ←