القسم الحالي: رموز الأخطاء

رموز الأخطاء

تستخدم واجهة API رموز حالة HTTP القياسية للإشارة إلى نتائج الطلبات، وتُعيد رسائل الأخطاء بصيغة JSON منظمة توضح نوع الخطأ وسببه.

رموز أخطاء HTTP

400INVALID_ROUTE

تم استخدام مسار API غير صحيح. تتضمن الاستجابة اقتراحاً للمسار الصحيح.

401AUTH_REQUIRED

لم يتم تضمين الترويسة X-API-Key في الطلب. تحتوي الاستجابة على رمز الخطأ في error.code وتفاصيل إضافية في detail.

403INVALID_API_KEY

صيغة مفتاح API غير صحيحة، أو أن المفتاح المستخدم غير صالح أو تم إلغاؤه. تحتوي الاستجابة على error.code وdetail.

403PLAN_LIMIT

تتطلب الخدمة المطلوبة باقة أعلى من الباقة الحالية، مثل الوصول إلى البيانات التاريخية الذي يتطلب Starter أو أعلى، أو طلب مجموعات من البيانات المالية غير متاحة ضمن باقة Starter.

404INVALID_SYMBOL

لم يتم العثور على رمز التداول المطلوب.

404 / 409INVALID_IDENTIFIER / AMBIGUOUS_IDENTIFIER

تعذّر العثور على شركة تطابق المعرّف المُدخل، أو أن المعرّف يطابق أكثر من شركة، مما يتطلب تحديد الشركة المطلوبة بشكل أدق.

429RATE_LIMITED(حدود الخوادم الطرفية)

تم تجاوز الحد المسموح به لمعدل الطلبات أو الاتصالات على مستوى خادم Nginx، قبل وصول الطلب إلى التطبيق. تتضمن الاستجابة error.code وerror.message.

429RATE_LIMITED(حدود التطبيق)

تم تجاوز الحصة اليومية، أو الحد الأقصى للطلبات في الدقيقة، أو أحد حدود الاستخدام المرتبطة بعنوان IP، أو تم تطبيق حد أمني مؤقت. تتضمن الاستجابة error.code وdetail.

500SERVER_ERROR

حدث خطأ داخلي في الخادم. أعد المحاولة، أو تواصل مع فريق الدعم إذا استمرت المشكلة.

الحدود الأمنية المؤقتة للحسابات الجديدة

قد تُطبّق حدود أمنية مؤقتة على بعض الحسابات الجديدة في الباقة المجانية. عند بلوغ هذا الحد، تُعيد واجهة API استجابة برمز HTTP 429، وتتضمن قيمة الحقل detail العبارة Temporary security limit reached. إذا توفرت الترويسة Retry-After، التزم بمدة الانتظار المحددة فيها قبل إعادة المحاولة.

مثال على استخدام مسار API غير صحيح: من الأخطاء الشائعة عند التكامل استدعاء المسار GET /api/v1/quote/batch/. في هذه الحالة، تُعيد واجهة API الخطأ 400 INVALID_ROUTE، مع اقتراح المسار الصحيح.

json
{
  "error": {
    "code": "INVALID_ROUTE",
    "message": "Did you mean /api/v1/quotes/?symbols=2222,1120 ?"
  }
}

تتضمن الاستجابات الناتجة عن عدم إرفاق مفتاح API (401)، أو استخدام مفتاح غير صالح أو مُلغى (403)، أو تجاوز حصة الاستخدام أو حدود الطلبات (429)، الحقلين error.code وerror.message، مع الاحتفاظ بالحقل detail. وعند تجاوز حصة الاستخدام اليومية (429)، يظهر الكائن upgrade إلى جانب الكائن error في الاستجابة.

صيغ استجابات الأخطاء

تستخدم أخطاء التحقق من بيانات الطلب والبحث عن الموارد عادةً كائن error منظماً، كما في المثال التالي:

json
{
  "error": {
    "code": "INVALID_SYMBOL",
    "message": "Stock symbol '9999' not found."
  }
}

عند تجاوز الحد المسموح به لمعدل الطلبات على مستوى Nginx، يُعاد الخطأ HTTP 429 قبل معالجة الطلب داخل التطبيق. في هذه الحالة، تكون قيمة الترويسة Retry-After هي 1، وتُستخدم بنية الاستجابة نفسها على النطاقين api.sahmk.sa وapp.sahmk.sa:

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded. Please retry shortly."
  }
}

تتضمن استجابات الأخطاء المتعلقة بمفتاح API المفقود أو المرفوض، والحصة اليومية، وحدود الطلبات في الدقيقة، وحدود عنوان IP، والقيود الأمنية المؤقتة، رمز الخطأ في error.code مع الاحتفاظ بالحقل detail. وعند تجاوز حصة الاستخدام اليومية، يظهر الكائن upgrade إلى جانب الكائن error.

json
{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "A valid X-API-Key is required."
  },
  "detail": "A valid X-API-Key is required."
}

آخر تحديث في