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

دليل شامل لرموز أخطاء Smart Money API، ورموز حالة HTTP، وخطوات استكشاف الأخطاء. فهم استجابات الأخطاء وحل مشاكل التكامل بسرعة.

رموز النجاح 2xx

تشير استجابات النجاح إلى أن الطلب تمت معالجته بنجاح.

الكود	الحالة	المعنى
200	OK	نجاح الطلب. يحتوي نص الاستجابة على البيانات المطلوبة.
201	Created	تم إنشاء المورد بنجاح. يتضمن الاستجابة المورد الجديد.
204	No Content	نجاح الطلب ولكن لا يوجد محتوى لإرجاعه (مثل DELETE).

مثال على استجابة 200

JSON

{
  "success": true,
  "data": {
    "total": 42,
    "positions": [...],
    "pagination": {
      "page": 1,
      "limit": 50
    }
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

رموز أخطاء العميل 4xx

تشير أخطاء العميل إلى أن الطلب كان غير صحيح أو غير صالح. أصلح طلبك وأعد المحاولة.

الكود	الحالة	السبب
400	Bad Request	بناء جملة الطلب غير صحيح. تحقق من معلمات الاستعلام والرؤوس ونص الطلب.
401	Unauthorized	بيانات اعتماد المصادقة مفقودة أو غير صالحة. تحقق من مفتاح API أو رمز JWT.
402	Payment Required	فشل دفع الاشتراك الخاص بك. قم بتحديث معلومات الفوترة في حسابك.
403	Forbidden	تمت المصادقة ولكن غير مصرح بهذا المورد. خطتك لا تتضمن هذه الميزة.
404	Not Found	الموارد غير موجودة. تحقق من عنوان URL للنقطة الطرفية والمعلمات.
429	Too Many Requests	تم تجاوز حد المعدل. انتظر قبل إعادة المحاولة. تحقق من رأس Retry-After.
422	Unprocessable Entity	فشل التحقق. معلمات الطلب غير صالحة أو مفقودة للحقول المطلوبة.

أمثلة على أخطاء المصادقة

مفتاح API مفقود (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_MISSING_KEY",
    "message": "بيانات اعتماد المصادقة غير متوفرة.",
    "resolution": "قم بتضمين مفتاح API في رأس Authorization: Authorization: Bearer sk_live_..."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

مفتاح API غير صالح (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "مفتاح API غير صالح أو منتهي الصلاحية.",
    "resolution": "قم بإنشاء مفتاح API جديد من لوحة التحكم الخاصة بك على https://smartmoneyapi.com/console"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

تقييد المعدل (429)

عند تجاوز حصة API الخاصة بك، يُرجع الخادم 429 Too Many Requests. تحقق من رؤوس الاستجابة لمعلومات تقييد المعدل:

رؤوس HTTP

X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600

استجابة خطأ تقييد المعدل

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "تم تجاوز حد طلبات API اليومي (10).",
    "resolution": "قم بالترقية إلى خطة Trader (29 دولارًا/شهر، 400 طلب/يوم) أو Pro (79 دولارًا/شهر، 4,000 طلب/يوم).",
    "reset_at": "2026-03-22T09:00:00Z"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

أخطاء التحقق (422)

تحدث أخطاء التحقق عندما تكون معلمات الطلب غير صالحة أو مفقودة للحقول المطلوبة.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "فشل تحقق الطلب.",
    "details": [
      {
        "field": "symbol",
        "error": "زوج تداول غير صالح. التنسيق المتوقع: BTCUSDT"
      },
      {
        "field": "min_position_size",
        "error": "يجب أن يكون رقمًا موجبًا"
      }
    ],
    "resolution": "أصلح أخطاء التحقق وأعد المحاولة."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

رموز أخطاء الخادم 5xx

تشير أخطاء الخادم إلى مشكلة من جانبنا. هذه مؤقتة وعادة ما يتم حلها بسرعة. قم بتنفيذ منطق إعادة المحاولة بالتراجع الأسي.

الكود	الحالة	الإجراء
500	Internal Error	خطأ غير متوقع في الخادم. أعد المحاولة بالتراجع الأسي.
502	Bad Gateway	انقطاع مؤقت في الخدمة. أعد المحاولة بعد بضع ثوانٍ.
503	Service Unavailable	صيانة أو انقطاع مؤقت. تحقق من صفحة الحالة. أعد المحاولة بعد فترة Retry-After.
504	Gateway Timeout	استغرق الطلب وقتًا طويلاً. ربما قام الخادم بمعالجته على أي حال. تحقق من عدم التكرار.

مثال على خطأ الخادم (503)

JSON

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "الخدمة غير متوفرة مؤقتًا بسبب الصيانة.",
    "resolution": "يرجى إعادة المحاولة بعد 5 دقائق. تتبع الحالة على https://status.smartmoneyapi.com"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

دليل استكشاف الأخطاء وإصلاحها

401 غير مصرح - مفتاح API غير صالح

المشكلة: تلقي أخطاء 401 حتى مع وجود مفتاح API.

الحلول:

تحقق من تضمين مفتاح API في رأس Authorization مع بادئة "Bearer"
تحقق من أن مفتاح API لم ينتهي صلاحيته أو تم إلغاؤه
تأكد من أنك تستخدم المفتاح الصحيح (الإنتاج، الاختبار، أو التطوير)
قم بإنشاء مفتاح API جديد من لوحة التحكم إذا فقدت الحالي

403 ممنوع - الميزة غير متاحة

المشكلة: الحصول على أخطاء 403 في نقاط نهاية معينة.

الحلول:

تحقق من مستوى API الخاص بك. تتطلب بعض النقاط الطرفية خطط Trader أو Pro
قم بالترقية إلى خطة في /pricing.html للوصول إلى الميزات المميزة
تحقق من أن مفتاح API لديه النطاقات المطلوبة ممكّنة
اتصل بالدعم إذا كنت تعتقد أنه يجب أن يكون لديك حق الوصول

429 طلبات كثيرة جدًا - تقييد المعدل

المشكلة: الحصول على أخطاء 429 وتقييد المعدل.

الحلول:

قم بتنفيذ منطق إعادة المحاولة بالتراجع الأسي (انتظر 1 ثانية، 2 ثانية، 4 ثوانٍ، إلخ.)
قم بتخزين الاستجابات مؤقتًا لتجنب استدعاءات API الزائدة
استخدم WebSocket للبيانات في الوقت الفعلي بدلاً من استطلاع نقاط نهاية REST
قم بالترقية إلى خطة للحصول على حصص أعلى (Trader 1,000/يوم، Pro 5,000/يوم)
اجمع استعلامات متعددة في طلبات فردية حيثما أمكن

400 طلب غير صالح - معلمات غير صالحة

المشكلة: تلقي أخطاء 400 مع طلبات غير صالحة.

الحلول:

تحقق من وثائق API للحصول على المعلمات المطلوبة والاختيارية
تحقق من أنواع المعلمات (سلاسل نصية مقابل أرقام، مصفوفات مقابل كائنات)
تأكد من أن JSON صالح ومُنسق بشكل صحيح
استخدم عناوين URL للنقاط الطرفية الصحيحة مع معلمات المسار المناسبة
التحقق من الأخطاء المطبعية في أسماء معاملات الاستعلام

أخطاء الخادم 5xx - انقطاعات مؤقتة

المشكلة: الحصول على أخطاء 500، 502، 503، أو 504.

الحلول:

تحقق من حالة الخدمة على https://status.smartmoneyapi.com
تنفيذ إعادة محاولة تلقائية مع تراجع أسي (بحد أقصى 5-10 محاولات)
انتظر 30-60 ثانية قبل إعادة محاولة أخطاء 503
استخدم رأس Retry-After لتحديد توقيت إعادة المحاولة
اشترك في صفحة الحالة للحصول على إشعارات الحوادث

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

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

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "رسالة خطأ مفهومة للبشر",
    "details": {...},
    "resolution": "خطوات لحل المشكلة"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

هل تحتاج إلى مساعدة إضافية؟

تحقق من وثائق API الخاصة بنا أو اتصل بالدعم مع رمز الخطأ وتفاصيل الطلب.

مرجع API

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

لديك أسئلة؟ تحقق من وثائقنا أو تواصل مع الدعم.

فتح وحدة التحكم