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

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

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

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

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

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

رموز حالة HTTP

2xx Success

4xx Client Errors

5xx Server Errors

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

400 Bad Request

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

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

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

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

401 Unauthorized

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

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

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

-H "Authorization: Bearer minds_your_api_key"

403 Forbidden

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

{
  "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
  }
}

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

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

404 Not Found

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

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

415 Unsupported Media Type

Content-Type خاطئ:

{
  "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:

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

Rate Limits

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

حدود الباقات

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

مثال على حد Minds

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

{
  "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

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

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

يؤدي بدء التحقق من الجمهور لجمهور لديه أقل من 10 Minds جاهزة إلى إرجاع 422 مع الرمز AUDIENCE_TOO_SMALL. أما الجمهور الأكبر مما تسمح به خطتك في الدراسة الواحدة فيُرفض بخطأ حدود الخطة القياسي الموضح أعلاه.

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

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

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

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

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
• تطلب رفع ملفات أكبر
• ترغب في دعم ذي أولوية

عرض الباقات

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

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

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

• حالة خدمة Minds
• تابع @mindsai_co للتحديثات

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

إذا واجهت:

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

تواصل معنا:

• نموذج الملاحظات
• Email: [email protected]

راجع الوثائق

• API Overview
• Authentication
• Minds API
• Knowledge API
• Chat API

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

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

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