الأخطاء ورموز الحالة

تستخدم واجهة finlight API رموز حالة HTTP المعتادة للإشارة إلى نتيجة الطلب. تعني الحالة 2xx النجاح؛ وتعني 4xx أن الطلب رُفض (عادةً شيء يمكنك إصلاحه)؛ وتعني 5xx وجود مشكلة لدينا. ويُرجع كل خطأ جسم JSON يصف ما حدث من خطأ.

ملاحظة: تُصادَق طلبات REST وWebSocket باستخدام ترويسة X-API-KEY. ويؤدّي المفتاح المفقود أو غير الصالح إلى إرجاع 401. (أما مصادقة تسليم webhook —الترويسات التي يرسلها finlight إلى نقطة النهاية الخاصة بك— فهي منفصلة؛ راجع مصادقة Webhook.)

رموز الحالة بلمحة

400 — Bad Request

يُرجَع عندما تفشل معاملات الاستعلام أو جسم الطلب في التحقّق، أو عندما تستخدم سلسلة query صياغة غير صالحة على مستوى الحقول.

معامل غير صالح:

{
  "statusCode": 400,
  "message": ["pageSize must not be greater than 100"],
  "error": "Bad Request"
}

صياغة query غير صالحة (POST /v2/articles):

{
  "statusCode": 400,
  "message": [
    {
      "property": "query",
      "constraints": { "query": "Invalid query syntax near 'ticker:'" }
    }
  ],
  "error": "Bad Request"
}

راجع إنشاء الاستعلامات المتقدمة للاطّلاع على صياغة query الصحيحة.

401 — Unauthorized

ترويسة X-API-KEY مفقودة أو غير صحيحة الصياغة أو ليست مفتاحًا صالحًا.

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

احصل على مفتاحك أو بدِّله من لوحة تحكم finlight.

403 — Forbidden

الطلب مُصادَق عليه، لكن باقتك لا تتضمّن الإمكانية المطلوبة — على سبيل المثال، طلب محتوى المقال الكامل في باقة لا تتضمّنه.

{
  "statusCode": 403,
  "message": "Your subscription does not allow calling the extended article content"
}

راجع حدود المعدل والحصص لمعرفة الإمكانات التي تتضمّنها كل باقة.

404 — Not Found

المورد المطلوب غير موجود — وأكثر الحالات شيوعًا هي GET /v2/articles/by-link برابط link لم يُفهرسه finlight.

{
  "statusCode": 404,
  "message": "Article not found"
}

422 — Unprocessable Entity

تتحقّق بعض نقاط النهاية عبر المُحقِّق العام، الذي يُرجع خريطة أخطاء مفتاحها هو الحقل. كل مفتاح هو الحقل المُخطئ؛ والقيمة تسرد القيود التي فشلت.

{
  "status": 422,
  "errors": {
    "language": "language must be a string"
  }
}

ملاحظة: قد تظهر إخفاقات التحقّق على هيئة 400 (في نقاط نهاية المقالات) أو 422 (المُحقِّق العام)، تبعًا للمسار — وكلاهما يشير إلى طلب خاطئ. افحص الجسم لمعرفة الحقل الذي فشل.

429 — Too Many Requests

لقد تجاوزت أحد حدود الاستخدام. هناك حالتان مختلفتان، لكل منهما رسالة محدّدة:

تجاوز حصة الطلبات الشهرية:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded token limit of 5000 for the current period."
}

تجاوز معدل الدفعات (قصير الأمد):

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded rate limit of 10 requests per 10 seconds."
}

ملاحظة: لا يُرجع finlight حاليًا ترويسات Retry-After أو ترويسات حد المعدل. بالنسبة لـ 429 الدفعات، تراجع وأعد المحاولة بعد نحو 10 ثوانٍ. وبالنسبة لـ 429 الحصة الشهرية، ستنجح الطلبات مجددًا في بداية دورة الفوترة التالية (أو بعد الترقية). راجع حدود المعدل والحصص.

500 — Internal Server Error

حدث خطأ غير متوقّع من جانب finlight. وهذه الأخطاء عابرة — أعد المحاولة مع تراجع تدريجي، وإذا استمرّت فتواصل معنا عبر الدعم.

{
  "statusCode": 500,
  "message": "Internal server error"
}

التعامل الجيّد مع الأخطاء

• تحقّق دائمًا من رمز الحالة أولًا، ثم اقرأ جسم JSON لمعرفة التفاصيل.
• أخطاء 4xx (باستثناء 429) هي خطؤك — أصلِح الطلب؛ فإعادة المحاولة دون تغيير لن تُجدي.
• 429 و5xx قابلان لإعادة المحاولة — استخدم التراجع الأسّي. وبالنسبة لـ 429 الدفعات، يكفي نحو 10 ثوانٍ.
• تصل أخطاء WebSocket على هيئة رسالة خادم error على المقبس بدلًا من حالة HTTP — راجع أساسيات WebSocket.
• تُتعقَّب إخفاقات تسليم Webhook (إلى نقطة النهاية الخاصة بك) في لوحة التحكم، ولا تُرجَع إليك بشكل متزامن — راجع اختبار Webhook.