---
title: "الأخطاء والحدود"
description: "فهم أخطاء API ورموز الحالة وحدود الموارد حسب الباقة."
---

# الأخطاء والحدود

فهم أخطاء API و rate limits وقيود الباقات.

## تنسيق استجابة الخطأ

تتبع جميع الأخطاء تنسيقاً موحداً:

```json
{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/minds",
  "error": true
}
```

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        statusCode
      </code>
    </td>
    
    <td>
      رمز حالة HTTP
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        statusMessage
      </code>
    </td>
    
    <td>
      وصف الخطأ بصيغة مقروءة (يُضبط لكل خطأ من قبل المعالج — لأخطاء التحقق يكون هذا المشكلة المحددة، مثلاً <code>
        "Mind not found"
      </code>
      
       أو <code>
        "Invalid Mind ID format"
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        message
      </code>
    </td>
    
    <td>
      نفس محتوى <code>
        statusMessage
      </code>
      
       لأخطاء v1. محجوز لمحتوى الـ stack/سياق إضافي في استجابات <code>
        5xx
      </code>
      
       في بنايات التصحيح.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      مسار الطلب (يُضيفه Nuxt H3)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       لاستجابات الخطأ (يُضيفه Nuxt H3)
    </td>
  </tr>
</tbody>
</table>

> اعتمد دائماً على `statusCode` للمعالجة البرمجية وعلى `statusMessage` (أو `message`) للسبب المقروء. الحقلان `url` و`error` بيانات تعريف مساعدة من الإطار الأساسي.

## رموز حالة HTTP

### 2xx Success

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      200
    </td>
    
    <td>
      OK
    </td>
    
    <td>
      نجح الطلب
    </td>
  </tr>
  
  <tr>
    <td>
      201
    </td>
    
    <td>
      Created
    </td>
    
    <td>
      تم إنشاء المورد بنجاح (مثلاً <code>
        POST /minds
      </code>
      
      , <code>
        POST /minds/{id}/knowledge
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      202
    </td>
    
    <td>
      Accepted
    </td>
    
    <td>
      تم قبول الطلب للمعالجة غير المتزامنة (مثلاً <code>
        POST /minds/{id}/knowledge
      </code>
      
       مع <code>
        keywords
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      204
    </td>
    
    <td>
      No Content
    </td>
    
    <td>
      نجح الطلب بدون جسم استجابة (مثلاً <code>
        DELETE /minds/{id}/knowledge/{itemId}
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 4xx Client Errors

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      400
    </td>
    
    <td>
      Bad Request
    </td>
    
    <td>
      معاملات طلب غير صالحة
    </td>
  </tr>
  
  <tr>
    <td>
      401
    </td>
    
    <td>
      Unauthorized
    </td>
    
    <td>
      مفتاح API مفقود أو غير صالح
    </td>
  </tr>
  
  <tr>
    <td>
      403
    </td>
    
    <td>
      Forbidden
    </td>
    
    <td>
      تم رفض الوصول أو تم بلوغ حد الباقة
    </td>
  </tr>
  
  <tr>
    <td>
      404
    </td>
    
    <td>
      Not Found
    </td>
    
    <td>
      المورد غير موجود
    </td>
  </tr>
  
  <tr>
    <td>
      415
    </td>
    
    <td>
      Unsupported Media Type
    </td>
    
    <td>
      ترويسة Content-Type خاطئة
    </td>
  </tr>
  
  <tr>
    <td>
      422
    </td>
    
    <td>
      Unprocessable Entity
    </td>
    
    <td>
      الطلب سليم البنية لكن لا يمكن تنفيذه، مثل بدء التحقق من جمهور لديه أقل من 10 Minds جاهزة (<code>
        AUDIENCE_TOO_SMALL
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      Too Many Requests
    </td>
    
    <td>
      تم تجاوز rate limit
    </td>
  </tr>
</tbody>
</table>

### 5xx Server Errors

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      500
    </td>
    
    <td>
      Internal Server Error
    </td>
    
    <td>
      خطأ من جانب الخادم
    </td>
  </tr>
  
  <tr>
    <td>
      503
    </td>
    
    <td>
      Service Unavailable
    </td>
    
    <td>
      الخدمة غير متاحة مؤقتاً
    </td>
  </tr>
</tbody>
</table>

## الأخطاء الشائعة

### 400 Bad Request

**حقل مطلوب مفقود:**

```json
{
  "statusCode": 400,
  "statusMessage": "Name is required"
}
```

**إدخال غير صالح:**

```json
{
  "statusCode": 400,
  "statusMessage": "File too large: document.pdf (55.2MB). Maximum size is 50MB."
}
```

### 401 Unauthorized

**مفتاح API مفقود:**

```json
{
  "statusCode": 401,
  "statusMessage": "Unauthorized"
}
```

**الحل:** ضمّن ترويسة `Authorization`:

```bash
-H "Authorization: Bearer minds_your_api_key"
```

### 403 Forbidden

**تم بلوغ حد الباقة:**

```json
{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}
```

**تم رفض الوصول:**

```json
{
  "statusCode": 403,
  "statusMessage": "Access denied"
}
```

### 404 Not Found

**المورد غير موجود:**

```json
{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}
```

### 415 Unsupported Media Type

**Content-Type خاطئ:**

```json
{
  "statusCode": 415,
  "statusMessage": "Unsupported Content-Type. Use application/json for links or multipart/form-data for files"
}
```

**الحل:** استخدم ترويسة `Content-Type` الصحيحة:

- `application/json` لطلبات JSON
- `multipart/form-data` لرفع الملفات

### 429 Too Many Requests

**تم تجاوز Rate Limit:**

```json
{
  "statusCode": 429,
  "statusMessage": "Too many requests. Please try again later."
}
```

## Rate Limits

يفرض v1 API حداً ثابت النافذة لكل حساب مصادق عليه. الحد الافتراضي للنشر هو 300 طلب في الدقيقة، لكنه قابل للضبط. اقرأ دائماً `RateLimit-Limit` و`RateLimit-Remaining`، وعند `429` انتظر عدد الثواني في `Retry-After`.

## حدود الباقات

راجع [جدول حدود الباقات المُنشأ](/docs/api/overview) للاطلاع على القيم العامة الحالية. قد تختلف التجاوزات التعاقدية، لذلك تكون `data.limit` و`data.current` في خطأ مصادق عليه هي القيم المعتمدة لذلك الطلب. تظهر باقة Individual باسم `"premium"` في حمولات API.

### مثال على حد Minds

**خطأ عند بلوغ الحد:**

```json
{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}
```

### حدود رفع المعرفة

- **حجم الملف:** حد أقصى 50MB لكل ملف (لجميع الباقات)
- **التخزين:** لا توجد حدود تخزين صريحة مفروضة حالياً

### حدود مفاتيح API

- **الحد الأقصى للمفاتيح:** لا يُفرض حاليًا أي حد أقصى.

## إخفاقات التحقق من الجمهور

يؤدي بدء [التحقق من الجمهور](/docs/api/audiences) لجمهور لديه أقل من 10 Minds جاهزة إلى إرجاع `422` مع الرمز `AUDIENCE_TOO_SMALL`. أما الجمهور الأكبر مما تسمح به خطتك في الدراسة الواحدة فيُرفض بخطأ حدود الخطة القياسي الموضح أعلاه.

بعد البدء بنجاح، يعمل التحقق في الخلفية، لذا فإن معظم الإخفاقات ليست أخطاء HTTP. اقرأها بدلاً من ذلك من الحقل `failure` في دفعة التحقق. قد تنتهي الدفعة بأحد الرموز التالية:

<table>
<thead>
  <tr>
    <th>
      الرمز
    </th>
    
    <th>
      المعنى
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        AUDIENCE_TOO_SMALL
      </code>
    </td>
    
    <td>
      لدى الجمهور أقل من 10 Minds جاهزة. يُعاد أيضاً على شكل <code>
        422
      </code>
      
       عند بدء التحقق
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MINDS_NEED_RETRAINING
      </code>
    </td>
    
    <td>
      تحتاج Minds في الجمهور إلى إعادة تدريب قبل أن تتمكن من الإجابة
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NOT_ENOUGH_QUESTIONS
      </code>
    </td>
    
    <td>
      أقل من 8 أسئلة تناسب الجمهور، لذلك لم يُطرح أي سؤال
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NOT_ENOUGH_RESPONSES
      </code>
    </td>
    
    <td>
      يحتاج التشغيل إلى إجابات اصطناعية أكثر مما تبقى لديك
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NO_FITTING_SURVEY
      </code>
    </td>
    
    <td>
      لا يوجد استطلاع منشور يناسب الجمهور
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NO_USABLE_SURVEY
      </code>
    </td>
    
    <td>
      لا يمكن لأي من الاستطلاعات التحقق من هذا الجمهور
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NO_SCORE
      </code>
    </td>
    
    <td>
      تعذّر منح درجة لأي من الاستطلاعات لهذا الجمهور
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        RUNS_REFUSED
      </code>
    </td>
    
    <td>
      تعذّر بدء تشغيل التحقق
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SURVEY_NOT_FOUND
      </code>
    </td>
    
    <td>
      تعذّر العثور على استطلاع محدد
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SURVEY_FILES_UNREADABLE
      </code>
    </td>
    
    <td>
      تعذّرت قراءة ملفات الاستطلاع المرفوعة
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SURVEY_RESULTS_NOT_FOUND
      </code>
    </td>
    
    <td>
      لا تحتوي الملفات المرفوعة على نتائج منشورة للمقارنة بها
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        VALIDATION_TOO_LARGE
      </code>
    </td>
    
    <td>
      سيطلب التحقق أكثر من 30,000 إجابة
    </td>
  </tr>
</tbody>
</table>

## أفضل الممارسات

### معالجة الأخطاء

**عالج الأخطاء دائماً:**

```javascript
async function requestJson(url, apiKey, data) {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  const text = await response.text();
  let result = null;
  if (text) {
    try {
      result = JSON.parse(text);
    } catch {
      if (response.ok) throw new Error('Expected a JSON response');
    }
  }
  if (!response.ok) {
    throw Object.assign(new Error(result?.statusMessage || result?.message || `HTTP ${response.status}`), {
      status: response.status,
      data: result?.data,
      retryAfter: response.headers.get('Retry-After')
    });
  }
  return result;
}
```

### منطق إعادة المحاولة

**طبّق إعادات محاولة ذكية:**

- أعد محاولة القراءة عند استجابات `429` أو `5xx` المؤقتة باستخدام تراجع أُسّي محدود، والتزم بقيمة `Retry-After`. لا تُعد محاولة الكتابة إلا إذا وثّقت نقطة النهاية دعم عدم تكرار الأثر، مع الحفاظ على المفتاح نفسه ومحتوى الطلب نفسه. بعد مهلة ذات نتيجة غير مؤكدة، تحقّق من المورد أو المهمة الحالية قبل الإرسال مجددًا.
- استخدم exponential backoff
- اضبط حداً أقصى لعدد المحاولات
- لا تعيد المحاولة عند أخطاء `4xx` (باستثناء 429)

### المراقبة

**تتبّع استخدامك:**

- سجّل ترويسات rate limit
- راقب معدلات الأخطاء
- اضبط تنبيهات للأخطاء المتكررة
- تتبّع أوقات الاستجابة

### الترقية عند الحاجة

رقّ باقتك إذا كنت:

- تصل إلى rate limits بشكل متكرر
- تحتاج إلى المزيد من الـ minds
- تطلب رفع ملفات أكبر
- ترغب في دعم ذي أولوية

[عرض الباقات](/settings?tab=subscription)

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

### تحقق من الحالة

راقب حالة خدمتنا:

- [حالة خدمة Minds](https://uptime.getminds.ai)
- تابع [@mindsai_co](https://x.com/mindsai_co) للتحديثات

### تواصل مع الدعم

إذا واجهت:

- أخطاء 500 مستمرة
- rate limiting غير صحيح
- سلوك غير متوقع

تواصل معنا:

- نموذج الملاحظات
- Email: [support@getminds.ai](mailto:support@getminds.ai)

### راجع الوثائق

- [API Overview](/docs/api/overview)
- [Authentication](/docs/api/authentication)
- [Minds API](/docs/api/minds)
- [Knowledge API](/docs/api/knowledge)
- [Chat API](/docs/api/chat)

## مرجع رموز الحالة

مرجع سريع لجميع رموز حالة HTTP:

```text
2xx Success
├─ 200 OK
└─ 201 Created

4xx Client Error
├─ 400 Bad Request
├─ 401 Unauthorized
├─ 403 Forbidden
├─ 404 Not Found
├─ 415 Unsupported Media Type
└─ 429 Too Many Requests

5xx Server Error
├─ 500 Internal Server Error
└─ 503 Service Unavailable
```