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

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

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

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

{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/sparks",
  "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": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "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": "Spark 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.

حدود الباقات

الباقات المختلفة لها حدود موارد مختلفة.

حدود الـ Minds

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

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

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

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

حدود مفاتيح API

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

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

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

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

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

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.statusCode}: ${error.message}`);
    // Handle specific errors
    if (error.statusCode === 429) {
      // Implement retry logic
    }
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error('Network error:', error);
}

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

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

• أعد المحاولة عند 429 (rate limit) وأخطاء 5xx
• استخدم exponential backoff
• اضبط حداً أقصى لعدد المحاولات
• لا تعيد المحاولة عند أخطاء 4xx (باستثناء 429)

المراقبة

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

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

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

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

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

عرض الباقات

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

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

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

• صفحة الحالة (قريباً)
• تابع @mindsai_co للتحديثات

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

إذا واجهت:

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

تواصل معنا:

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

راجع الوثائق

• API Overview
• Authentication
• Sparks 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