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

تقدّم هذه الوثيقة معلومات مفصّلة عن رموز الأخطاء المتنوّعة التي قد تواجهها أثناء استخدام Claude Code وحلولها.

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

| الرمز | النوع | الوصف | الخطورة |
|------|------|-------------|----------|
| 400 | خطأ العميل | طلب مشوّه | منخفضة |
| 401 | خطأ مصادقة | مفتاح API غير صالح | متوسطة |
| 402 | خطأ الحصة / الخدمة | نفدت الحصة، أو الخدمة ترفض مؤقتًا | متوسطة |
| 403 | خطأ صلاحيات | تم رفض الوصول | متوسطة |
| 429 | حد معدل الطلبات | طلبات كثيرة جدًا | متوسطة |
| 500 | خطأ في الخادم | خطأ داخلي | مرتفعة |
| 502 | خطأ في البوابة | الواجهة الخلفية غير متاحة | مرتفعة |
| 503 | الخدمة غير متاحة | محمّلة بشكل زائد مؤقتًا | مرتفعة |
| 529 | API محمّل بشكل زائد | Claude API محمّل بشكل زائد | مرتفعة |

---

## 429 - طلبات كثيرة جدًا

أحد الأخطاء الأكثر شيوعًا، ويشير إلى طلبات كثيرة جدًا خلال فترة قصيرة.

### رسالة الخطأ

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

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

1. **طلبات متكررة جدًا**: إرسال عدة طلبات بتتابع سريع

2. **الطلبات المتزامنة كثيرة جدًا**: تشغيل عدة نسخ من Claude Code في وقت واحد

3. **بلوغ حد token**: استهلاك عدد كبير جدًا من token في وقت قصير

> **نفاد الحصة ليس خطأ 429**: عندما تنفد الحصة اليومية أو الإجمالية أو الأسبوعية، تكون الاستجابة **402** (`insufficient_quota`) — راجع [نفاد الحصة](#402-quota-exhausted) في هذه الصفحة.

### الحلول

**إجراءات فورية**:
```bash
# Wait 30-60 seconds before retrying
sleep 60 && claude "your question"
```

**حلول طويلة الأمد**:

1. قلّل تكرار الطلبات، وتجنّب الإرسال المتتابع السريع

2. استخدم الأمر `/compact` لضغط السياق

3. قسّم المهام الكبيرة إلى دفعات أصغر

> **ميزة QCode.cc**: موازنة تحميل احترافية لتوزيع ضغط الطلبات، مما يقلل أخطاء 429 بفعالية.

---

## 502 - بوابة غير صالحة

يشير إلى أن البوابة أو خادم الوكيل تلقّى استجابة غير صالحة من الواجهة الخلفية.

### رسالة الخطأ

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

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

1. **الواجهة الخلفية غير متاحة مؤقتًا**: مشكلات في خادم Anthropic API

2. **انقطاع اتصال الشبكة**: انقطع الاتصال أثناء الطلب

3. **مشكلات خادم الوكيل**: فشل عقدة وسيطة

4. **انتهاء مهلة الطلب**: تجاوز زمن الاستجابة حد البوابة

### الحلول

**إجراءات فورية**:
```bash
# 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 غير صالح أو غياب مصادقة صالحة.

### رسالة الخطأ

```text
Error: 401 Unauthorized
Invalid API key or authentication token.
```

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

1. **مفتاح API غير صحيح**: حروف مفقودة أو مسافات إضافية عند النسخ

2. **مفتاح API منتهي الصلاحية**: انتهت صلاحية الاشتراك

3. **مفتاح API معطّل**: محظور بسبب انتهاك السياسة

4. **متغير البيئة غير مضبوط**: `ANTHROPIC_AUTH_TOKEN` غير مهيأ

### الحلول

**تحقق من مفتاح API**:
```bash
# Check environment variable
echo $ANTHROPIC_AUTH_TOKEN

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

**الخطوات**:

1. سجّل الدخول إلى [لوحة تحكم QCode.cc](https://qcode.cc/dashboard) للتحقق من حالة مفتاح API

2. تأكد من أن الاشتراك نشط

3. إذا كان محظورًا، فتواصل مع الدعم

---

## 402 - الدفع مطلوب

قد يعني 402 أمرين مختلفين؛ تحقق من جسم الاستجابة أولًا. إذا كانت `error.type` هي `insufficient_quota`، فإن **حصتك قد نفدت** (راجع [نفاد الحصة](#402-quota-exhausted))؛ وإلا فإن خدمة النموذج ترفض الطلب مؤقتًا (راجع [رفض الخدمة مؤقتًا](#402-service-refused)).

<a id="402-quota-exhausted"></a>

### نفاد الحصة (`insufficient_quota`)

تكون الاستجابة HTTP 402 مع `error.type` = `insufficient_quota`؛ ويخبرك `code` أي حصة نفدت:

| الرمز | المعنى | كيفية الاستعادة |
|------|---------|-----------------|
| `daily_cost_limit_exceeded` | نفدت الحصة اليومية | تُعاد تلقائيًا عند **00:00 بتوقيت بكين**؛ وإذا لم يكفِ اليوم، فاشترِ باقة التعزيز من [لوحة التحكم](https://qcode.cc/dashboard) |
| `total_cost_limit_exceeded` | نفدت الحصة الإجمالية؛ ينطبق على المفاتيح التي تُحتسب على حصة إجمالية، مثل الحصة الإجمالية لباقة من باقات الدفع حسب الاستخدام أو الحصة الشهرية لخطة Ultimate | تُستعاد وفقًا لقواعد خطتك: في باقات الدفع حسب الاستخدام، اشترِ أي باقة مرة أخرى للمتابعة على المفتاح نفسه؛ وتُشحن الحصة الشهرية لخطة Ultimate عند كل إعادة ضبط شهرية؛ وإذا لم تكن متأكدًا فتواصل مع الدعم |
| `weekly_opus_cost_limit_exceeded` | نفد الحد الأسبوعي لنماذج Claude | يُعاد تلقائيًا كل أسبوع؛ راجع [دليل لوحة التحكم](/docs/reference/dashboard-guide) |

مثال على جسم الاستجابة (نفدت الحصة الإجمالية):

```json
{
  "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 أعلاه.

---

<a id="402-service-refused"></a>

### الخدمة ترفض الطلب مؤقتًا

عندما لا يحمل جسم الاستجابة `insufficient_quota`، تكون سلسلة خدمة النموذج قد رفضت هذا الطلب. **عادةً لا تكون هذه مشكلة في مفتاحك أو في إعداداتك** — فالطلبات الصادرة من المفتاح نفسه إلى نماذج أخرى في الوقت نفسه تنجح عادةً.

#### ما تراه

```text
Error: 402 Payment Required
```

في Claude Code، يبدو الأمر عادةً وكأن الطلب يفشل ببساطة دون محتوى استجابة؛ ومن سكربت أو SDK تحصل على HTTP 402.

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

1. **خدمة النموذج غير متاحة مؤقتًا**: هذا النوع من 402 يأتي من سلسلة الخدمة، وترحّل بوابة QCode الحالة كما هي

2. **مركّز على نموذج واحد**: في أي لحظة قد يسجّل نموذج واحد نسبة 402 مرتفعة بينما تكون النماذج الأخرى سليمة تمامًا

3. **يعتمد على نطاق نقطة النهاية**: تمر النطاقات المختلفة عبر مسارات خدمة مختلفة، وقد يختلف احتمال مواجهة 402 اختلافًا كبيرًا

4. **لا علاقة له برصيدك**: هذا النوع من 402 لا يسببه نفاد الرصيد أو حصة الخطة؛ و402 الخاص بالحصة يحمل `insufficient_quota`، راجع [نفاد الحصة](#402-quota-exhausted) أعلاه

#### ما يجب فعله

**1. بدّل النموذج (الأكثر فاعلية)**

```bash
# Switch inside a session
/model sonnet

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

**2. بدّل نطاق نقطة النهاية**

```bash
# 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](/docs/getting-started/endpoints-and-api-paths).

**3. لا تكتب حلقة إعادة محاولة متلاحقة**

لا يزول 402 بإعادة الإرسال فورًا؛ والضغط المتكرر لا يزيد الأمر إلا سوءًا. استخدم التراجع الأسي، أو بدّل النموذج فحسب — راجع «أفضل ممارسات معالجة الأخطاء» في هذه الصفحة.

**4. إذا استمر الأمر، فتواصل مع الدعم**

ضمّن وقت حدوثه، ومعرّف النموذج، ونطاق نقطة النهاية، وتواصل معنا عبر [الدردشة المباشرة](javascript:void(Tawk_API.toggle())) أو [hi@qcode.cc](mailto:hi@qcode.cc).


#### `INSUFFICIENT_BALANCE` / `Insufficient account balance`

تحمل بعض استجابات 402/403 JSON مثل `"code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance"`. **هذا لا يعني أن رصيد QCode لديك قد نفد.** إنه حالة مؤقتة في مكان ما ضمن سلسلة الخدمة، تُمرَّر كما هي — ولا علاقة لها بحسابك. عندما تنفد حصتك أنت، يحمل جسم الاستجابة `insufficient_quota` مع رمز `*_cost_limit_exceeded` (راجع [نفاد الحصة](#402-quota-exhausted) أعلاه).

ما يجب فعله: انتظر وأعد المحاولة / بدّل النموذج / بدّل نطاق الوصول (الخطوات ①–③ أعلاه كلها تنطبق)؛ وإذا استمر الأمر، فتواصل مع الدعم مع معرّف الطلب. قائمة التحقق الكاملة: [دليل استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting).

---
## 403 - محظور

رفض الخادم الطلب، ويعود السبب عادةً إلى عدم كفاية الأذونات.

### رسالة الخطأ

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

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

1. **نقطة نهاية API خاطئة**: استخدام عنوان API غير صحيح

2. **أذونات غير كافية**: الخطة الحالية لا تدعم هذه الميزة

3. **قيود إقليمية**: بعض الميزات غير متاحة في مناطق معينة

4. **مشكلات حالة الحساب**: الحساب مقيّد

### الحلول

```bash
# 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؛ راجع [دليل استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting) لمعرفة الترتيب الكامل.

---

## 400 - طلب غير صالح

صيغة الطلب غير صحيحة أو المعاملات غير صالحة.

### رسالة الخطأ

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

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

1. **طلب مشوّه**: صيغة JSON غير صحيحة

2. **معاملات مفقودة**: لم تُقدَّم المعاملات المطلوبة

3. **قيم غير صالحة**: قيم المعاملات خارج النطاق المسموح

4. **مشكلات في الترميز**: الأحرف الخاصة غير مرمّزة بشكل صحيح

### الحلول

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

1. بسّط الإدخال واستبعد الأحرف الخاصة

2. تأكّد من أن مسارات الملفات تستخدم الترميز الصحيح

3. تحقّق من صيغة معاملات الأمر

---

## 500 - خطأ داخلي في الخادم

واجه الخادم حالة غير متوقعة منعت إكمال الطلب.

### رسالة الخطأ

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

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

1. **خطأ برمجي في الخادم**: مشكلة في شيفرة خادم API

2. **نفاد الموارد**: نضوب مؤقت في موارد الخادم

3. **خطأ في الإعداد**: إعداد خاطئ للخادم

### الحلول

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

# Use verbose mode for more info
claude --verbose
```

1. انتظر بضع دقائق ثم أعد المحاولة

2. تحقّق من حالة خدمة [QCode.cc](https://qcode.cc)

3. تواصل مع الدعم مع تفاصيل الخطأ إذا استمرت المشكلة

### E015 - تجاوز سياق المحادثة

يُطلق عندما يقترب سياق المحادثة من حد سعة النموذج (~95%). يغلّف QCode.cc هذا الخطأ كاستجابة 429 لتحفيز إعادة المحاولة:

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

**الحل**: راجع قسم «منع تجاوز الجلسة الطويلة» في [إدارة السياق](/docs/usage/context-management).

---
## 503 - الخدمة غير متاحة

يتعذر على الخادم مؤقتًا معالجة الطلبات، عادةً بسبب التحميل الزائد أو الصيانة.

### رسالة الخطأ

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

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

1. **التحميل الزائد على الخادم**: حجم الطلبات يتجاوز السعة

2. **صيانة مجدولة**: الخادم قيد الصيانة

3. **استنفاد الموارد**: موارد الخادم غير كافية مؤقتًا

### الحلول

```bash
# 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.

### رسالة الخطأ

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

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

1. **ارتفاع عالمي في الاستخدام**: زيادة حادة عالمية في مستخدمي خدمة Claude

2. **ساعات الذروة**: تركز الطلبات خلال ساعات العمل

3. **أحداث ذات إقبال كبير**: أحداث معينة تسبب ارتفاعًا في الاستخدام

### الحلول

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

1. انتظر من 2 إلى 5 دقائق ثم أعد المحاولة

2. تجنب ساعات الذروة (ساعات العمل في الولايات المتحدة)

3. استخدم `/compact` لتقليل استخدام token

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

---

## مهلة الاتصال

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

### رسالة الخطأ

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

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

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

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

3. **المهمة معقدة جدًا**: وقت معالجة الذكاء الاصطناعي طويل جدًا

4. **استجابة الخادم بطيئة**: حمل الخادم مرتفع

### الحلول

```bash
# Test network connection
ping api.qcode.cc

# Use compact mode to reduce context
/compact
```

1. تحقق من استقرار اتصال الشبكة

2. استخدم `/compact` لضغط السياق

3. قسّم المهام المعقدة إلى مهام أبسط

4. جرّب بيئة شبكة أكثر استقرارًا

---

## أخطاء خادم MCP

أخطاء قد تنشأ من إعداد خادم MCP أو وقت تشغيله.

### الأعراض

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

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

1. **أمر الخادم خاطئ**: خطأ مطبعي في اسم حزمة npx أو أنها غير مثبتة

2. **متغيرات بيئة مفقودة**: token الذي يحتاجه خادم MCP غير مضبوط

3. **مهلة**: بدء تشغيل الخادم أو تنفيذه يستغرق وقتًا طويلًا

4. **صلاحيات غير كافية**: رُفض الوصول إلى نظام الملفات / قاعدة البيانات

### الحلول

```bash
# 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. تشغيل التشخيص التلقائي

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

يتحقق هذا تلقائيًا من مشكلات التكوين الشائعة: متغيرات البيئة، واتصال API، وحالة خادم MCP، وغير ذلك.


### 1. التحقق من اتصال الشبكة

```bash
# 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. التحقق من متغيرات البيئة

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

### 3. تفعيل التسجيل المفصّل

```bash
# Use verbose mode for detailed info
claude --verbose

# Or set debug mode
DEBUG=true claude
```

### 4. اختبار طلب بسيط

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

### 5. التحقق من حالة الخدمة

زُر [QCode.cc](https://qcode.cc) للاطلاع على إعلانات حالة الخدمة.

---

## أفضل ممارسات معالجة الأخطاء

### تنفيذ آلية إعادة المحاولة

```bash
# 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](https://qcode.cc/dashboard)

2. اعرض إحصاءات الاستخدام

3. اضبط تنبيهات الاستخدام

### تحسين الطلبات

1. **تقليل السياق**: استخدم `/compact` أو `/clear` بانتظام

2. **المعالجة على دفعات**: قسّم المهام الكبيرة إلى مهام أصغر

3. **تجنّب التكرار**: خزّن النتائج الشائعة مؤقتًا

---

## الحصول على المساعدة

إذا لم تحل الحلول أعلاه مشكلتك، فتواصل مع دعم QCode.cc:

- **الدردشة المباشرة**: الزاوية اليمنى السفلية للموقع

- **وقت الاستجابة**: 1-2 ساعة خلال ساعات العمل

- **ساعات الدعم**: 10:00–22:00 يوميًا

عند التواصل مع الدعم، يُرجى تقديم:

1. رسالة الخطأ كاملة

2. الأمر المنفّذ

3. وقت الحدوث

4. بادئة مفتاح API (لا تشارك المفتاح كاملًا أبدًا)