الأخطاء

كيفية التعامل مع الأخطاء ورموز الحالة من واجهة برمجة التطبيقات API الخاصة بـ Benzinga

تستخدم واجهة برمجة التطبيقات API الخاصة بـ Benzinga رموز استجابة HTTP التقليدية للدلالة على نجاح أو فشل طلب الـ API. بشكل عام:

• 2xx: نجاح.
• 4xx: خطأ من جهة العميل (مثلًا، معلمة مفقودة، مفتاح غير صالح).
• 5xx: خطأ من جهة الخادم (حدث خلل ما من جانب Benzinga).

تحقَّق دائمًا أولًا من رمز حالة HTTP لتحديد ما إذا كان الطلب ناجحًا. لا تعتمد فقط على جسم الاستجابة، إذ يمكن أن يختلف التنسيق بين نقاط نهاية واجهة برمجة التطبيقات API المختلفة.

​

رموز حالات HTTP

يسرد الجدول التالي رموز الحالات القياسية التي قد تواجهها.

Code	Status	Description
200	OK	تم تنفيذ الطلب بنجاح.
400	Bad Request	الطلب غير مقبول، غالبًا بسبب معلمة مفقودة أو غير صالحة.
401	Unauthorized	لم يتم توفير مفتاح واجهة برمجة التطبيقات API صالح. تحقّق من ترويسة Authorization أو معامل token.
402	Request Failed	كانت المعلمات صالحة لكن الطلب فشل لأسباب تتعلق بمنطق الأعمال.
403	Forbidden	مفتاح واجهة برمجة التطبيقات API صالح، لكن لا تملك صلاحية الوصول إلى هذا المورد.
404	Not Found	المورد المطلوب (مثلًا: ID أو endpoint) غير موجود.
429	Too Many Requests	تجاوزت حد معدل الطلبات المسموح به.
500	Internal Server Error	حدث خطأ ما في خوادم Benzinga. هذه الحالات نادرة.
503	Service Unavailable	الخدمة غير متاحة مؤقتًا (مثلًا بسبب الصيانة).

​

أجسام استجابات الأخطاء

بينما يُعَدّ رمز حالة HTTP المؤشر الأساسي على حدوث خطأ، فإنّ جسم الاستجابة غالبًا ما يحتوي على تفاصيل تساعدك في اكتشاف الأخطاء وإصلاحها. يمكن أن يختلف تنسيق هذا الجسم باختلاف واجهة برمجة التطبيقات API التي تستدعيها.

​

التنسيق 1: رسالة خطأ بسيطة

تُرجِع العديد من نقاط النهاية (مثل واجهة برمجة التطبيقات News API) قيمة بسيطة من نوع string أو كائن JSON مسطّحًا يحتوي على رسالة.

"Invalid or Missing Query Parameters"

أو

{
  "message": "Invalid page size"
}

​

التنسيق 2: كائن خطأ منظم

واجهات برمجة التطبيقات API الأحدث (مثل Data API Proxy / الأساسيات المالية) تُرجِع كائنًا منظمًا يحتوي على قائمة بالأخطاء.

{
  "data": null,
  "errors": [
    {
      "code": "database_query_error",
      "id": "ERR_12345",
      "value": "Unable to fetch data for symbol: INVALID"
    }
  ],
  "ok": false
}

​

معالجة الأخطاء برمجياً

نظراً لإمكانية اختلاف أجسام الاستجابة، نوصي باعتماد استراتيجية قوية لمعالجة الأخطاء:

1. تحقق من رمز حالة HTTP. إذا كان >= 400، فاعتبره خطأً.
2. سجّل جسم الاستجابة. اكتب الجسم بالكامل في سجلاتك لأغراض تصحيح الأخطاء.
3. اعرض رسالة عامة. ما لم تكن متكاملاً مع نقطة نهاية محددة وتعرف صيغة الخطأ الخاصة بها بدقة، اعرض رسالة عامة مثل “حدث خطأ ما” للمستخدمين النهائيين إلى جانب رمز الحالة.