الأخطاء

تستخدم Partner API رموز حالة HTTP القياسية ونصوص استجابة بتنسيق JSON لتوضيح سبب إخفاق الطلب.

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

تُرجع معظم أخطاء API نصًا بتنسيق JSON يتضمن رسالة، وتفاصيل منظَّمة عند توفرها.

{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

تُرجع بعض نقاط النهاية الخاصة بمجالات محددة حالة وسببًا صريحين. على سبيل المثال، تتضمن حالات إخفاق التحكم في الوصول حقولًا مثل reason وdoor_id وfacility_id وevent_id.

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

رموز الحالة

400 Bad Request (طلب غير صالح)

الطلب مشوّه أو تنقصه حقول مطلوبة. أصلح الطلب قبل إعادة المحاولة.

401 Unauthorized (غير مصرّح به)

أخفقت المصادقة. تحقّق من أنك تستخدم HTTP Basic Auth مع مفتاح API السري بوصفه اسم المستخدم وكلمة مرور فارغة.

403 Forbidden (محظور)

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

404 Not Found (غير موجود)

لم يُعثر على المورد المطلوب أو أنه غير متاح لتكاملك.

409 Conflict (تعارض)

يتعارض الطلب مع الحالة الحالية للمورد. في التحكم في الوصول، قد يشمل ذلك وجود وحدة التحكم في الباب/البوابة في وضع الصيانة.

422 Unprocessable Entity (كيان غير قابل للمعالجة)

الطلب بتنسيق JSON صالح لكنه يخفق في التحقق الدلالي. أصلح البيانات قبل إعادة المحاولة.

429 Too Many Requests (طلبات كثيرة جدًا)

تجاوز التكامل حد المعدل الموثّق. أعِد المحاولة باستخدام التراجع الأُسّي.

500 Internal Server Error (خطأ داخلي في الخادم)

تعذّر على Performance Hub إكمال الطلب بسبب خطأ داخلي. أعِد المحاولة مع التراجع. وإذا استمرت المشكلة، فتواصل مع الدعم مع ذكر نقطة النهاية والطابع الزمني ونص الاستجابة.

503 Service Unavailable (الخدمة غير متاحة)

خدمة أو جهاز تعتمد عليه العملية غير متاح. في عمليات فتح أقفال وحدات التحكم في الأبواب/البوابات، قد يعني ذلك أن وحدة التحكم غير متصلة.

504 Gateway Timeout (انتهاء مهلة البوابة)

انتهت مهلة العملية. في عمليات فتح أقفال وحدات التحكم في الأبواب/البوابات، يعني ذلك أن فتح القفل لم يُؤكَّد قبل انتهاء فترة المهلة.

حالات إخفاق Access Time Window

يخفق التحقق من النوافذ قبل كتابة اللقطة غير الصالحة. ومن الأسباب الشائعة التي لا تُجدي معها إعادة المحاولة:

• غياب access_time_windows_revision عند وجود access_time_windows.
• قيم epoch نصية أو عشرية أو يُرجَّح أنها بالمللي ثانية.
• منطقة زمنية غير صالحة وفق IANA، أو فاصل زمني معكوس، أو external_id مكرر، أو كتل أسبوعية متداخلة، أو كتلة ليلية لم تُقسَّم.
• قيمة خارج حدود العدد أو الطول أو المدى الموثّقة.

تكرار المراجعة نفسها بمحتوى موحَّد مختلف يُعدّ 409 Conflict. قم بالتسوية مع أحدث حالة موثوقة وخصّص مراجعة أحدث؛ ولا تواصل إعادة محاولة الزوج المتعارض. ويُبلَّغ عن المراجعة الأقدم بوصفها لقطة قديمة تم تخطيها بدلًا من السماح لها بالكتابة فوق الحالة الأحدث. وأي scope_key غير معروف أو غير معيَّن يخفق بشكل مغلق في التفويض، وينبغي التعامل معه بوصفه تنبيهًا في التهيئة.

إذا انتهت مهلة التسليم أو تلقّى 5xx عابرًا، فأعِد محاولة اللقطة الموحَّدة نفسها تمامًا بالمراجعة نفسها. وإذا أخفق الجلب من المصدر، فاحذف حقل النوافذ بالكامل؛ ولا تستبدله أبدًا بمصفوفة فارغة.

إرشادات إعادة المحاولة

أعِد محاولة ما يلي باستخدام تراجع أُسّي محدود:

• 429
• 500
• 502
• 503
• 504

لا تُعِد محاولة ما يلي دون تمحيص:

• 400
• 401
• 403
• 404
• 409
• 422

في التحكم في الوصول، تعامل دائمًا مع استجابات انتهاء المهلة وعدم الاتصال على أنها إخفاق في فتح القفل، ما لم تنص قواعد الوصول وإجراءات السلامة الخاصة بك على خلاف ذلك.

تفاصيل يجب تضمينها عند طلب الدعم

عند التواصل مع الدعم، ضمّن ما يلي:

• نقطة النهاية وطريقة HTTP.
• الطابع الزمني والمنطقة الزمنية.
• معرّف مفتاح الشريك، وليس المفتاح السري.
• معرّف المنشأة المستخدم.
• معرّف السجل المصدر من نظامك.
• حالة الاستجابة ونصها.
• event_id أو command_id عند توفرهما.