Docs

الاخطاء وحدود الاستخدام

مرجع شامل لرموز الاخطاء وسياسات حدود الاستخدام

رموز حالة HTTP

الرمزالمعنىالوصف
200OKالطلب نجح
201Createdتم انشاء المورد بنجاح
400Bad Requestبيانات الطلب غير صحيحة
401Unauthorizedمفتاح API غير صالح او مفقود
403Forbiddenلا تملك صلاحية لهذا الاجراء
404Not Foundالمورد غير موجود
409Conflictتعارض مع الحالة الحالية
422Unprocessable Entityالبيانات صحيحة الشكل لكن غير قابلة للمعالجة
429Too Many Requestsتجاوز حد الاستخدام
500Internal Server Errorخطأ داخلي في الخادم

شكل رسالة الخطأ

جميع الاخطاء تُرجع بصيغة موحدة:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_AI_CREDITS",
    "message": "رصيد AI غير كافٍ لاتمام العملية",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}

رموز الاخطاء المخصصة

اخطاء المصادقة

الرمزالوصف
AUTH_TOKEN_EXPIREDانتهت صلاحية التوكن
AUTH_TOKEN_INVALIDالتوكن غير صالح
AUTH_INSUFFICIENT_PERMISSIONSصلاحيات غير كافية

اخطاء المتجر

الرمزالوصف
STORE_NOT_FOUNDالمتجر غير موجود
STORE_SUSPENDEDالمتجر موقوف
STORE_PLAN_LIMITتجاوز حد الخطة

اخطاء المنتجات

الرمزالوصف
PRODUCT_NOT_FOUNDالمنتج غير موجود
PRODUCT_OUT_OF_STOCKالمنتج نفذ من المخزون
PRODUCT_LIMIT_REACHEDوصلت لحد المنتجات في خطتك

اخطاء الـ AI

الرمزالوصف
INSUFFICIENT_AI_CREDITSرصيد AI غير كافٍ
AI_PROCESSING_FAILEDفشل في معالجة الـ AI
AI_IMAGE_INVALIDالصورة غير مناسبة للتحليل
AI_RATE_LIMITتجاوز حد طلبات AI

اخطاء الدفع

الرمزالوصف
PAYMENT_FAILEDفشل الدفع
PAYMENT_GATEWAY_ERRORخطأ في بوابة الدفع
REFUND_EXCEEDS_AMOUNTمبلغ الاسترداد اكبر من المبلغ الاصلي

حدود الاستخدام (Rate Limits)

حسب الخطة

الخطةالحدالفترة
اساسي100 طلبدقيقة
احترافي500 طلبدقيقة
مؤسسي2000 طلبدقيقة

حسب الـ Endpoint

المجموعةالحدالفترة
قراءة (GET)300/دقيقةعام
كتابة (POST/PUT/DELETE)100/دقيقةعام
AI Endpointsحسب الجدول اعلاهلكل endpoint
Webhooks50 webhook/متجراجمالي

هيدرات الحدود

كل استجابة تحتوي هيدرات تبيّن حالة الحدود:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1713100800

عند تجاوز الحد

عند تجاوز الحد، ستحصل على 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "تجاوزت حد الاستخدام. حاول بعد 45 ثانية.",
    "retry_after": 45
  }
}

نصيحة: استخدم Exponential Backoff عند الحصول على 429 -- انتظر 1 ثانية، ثم 2، ثم 4، وهكذا.