الأخطاء

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

تعيد واجهة برمجة التكامل رموز HTTP القياسية. تستخدم الطلبات مخطط IntegrationApiKey مع الترويسة X-Survanta-Api-Key. تستخدم حالات فشل المصادقة والتفويض بالنطاق غلاف JSON المشترك BaseResponse الذي يحتوي الحقول errorCode وerrorMessage وdata.

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

تعيد مفاتيح API المفقودة أو الفارغة أو غير الصالحة أو غير المعروفة HTTP 401 بهذه الاستجابة الدقيقة:

{
  "errorCode": 401,
  "errorMessage": "Authentication is required. Provide valid credentials or a valid API key.",
  "data": null
}

يعيد المفتاح المصادق الذي يفتقد النطاق المطلوب لنقطة النهاية HTTP 403 بهذه الاستجابة الدقيقة:

{
  "errorCode": 403,
  "errorMessage": "You do not have permission to access this resource.",
  "data": null
}

ينطبق هذان الغلافان الدقيقان على حالتي 401 و403 أعلاه. وقد تستخدم أخطاء ربط معاملات الاستعلام التي ينشئها إطار العمل شكل ASP.NET Core validation problem details.

رموز الحالة

400 طلب غير صحيح

الطلب مشوه أو يحتوي على قيم معاملات غير صالحة.

لا تحتوي إجراءات القراءة الحالية على نموذج جسم. تُطبّع قيم page وpageSize للاستجابات الخام وتُحصر بدل رفضها. وقد ينتج 400 من ربط المسار أو الاستعلام في إطار العمل عند إرسال قيم مشوهة.

الإجراء: صحح معاملات الطلب قبل إعادة المحاولة.

401 غير مصرح

مفتاح API مفقود أو فارغ أو غير صالح أو غير معروف، أو رفضت المصادقة العميل. يشمل الرفض العميل غير النشط أو الملغى أو المنتهي، أو المؤسسة غير النشطة، أو حظر الاشتراك، أو انعدام حد التكاملات الخارجية أو تجاوزه، أو غياب الوصول إلى API التقارير عن ReportsRead أوUsageRead، أو غياب الوصول إلى API الاستجابات الخام عن RawResponsesRead. تحدث هذه الحالات أثناء المصادقة، ولذلك تعيد 401 لا 403.

الأسباب الشائعة:

لم تُضمَّن الترويسة X-Survanta-Api-Key في الطلب.
قيمة المفتاح غير صحيحة أو بُترت أثناء النسخ واللصق.
أُلغي عميل التكامل من قِبل مسؤول مخوّل.
جرى تدوير المفتاح ولا تزال قيمة المفتاح القديم مستخدمة.

الإجراء: تحقق من أن المفتاح مُضمَّن في الترويسة X-Survanta-Api-Key بقيمته الكاملة. إذا جرى تدوير المفتاح أو إلغاؤه، حدّث النظام المستهلك بالمفتاح الجديد.

403 محظور

مفتاح API صالح لكن العميل لا يمتلك النطاق المطلوب من نقطة النهاية المطلوبة.

الأسباب الشائعة:

استدعاء بيانات الاستبيانات أو تقاريرها أو ملخصات الاستجابات بدون ReportsRead.
استدعاء نقطة نهاية الاستخدام بدون UsageRead.
استدعاء نقطة الاستجابات الخام أو تنزيل ملف استجابة بدون RawResponsesRead.

الإجراء: استخدم عميلًا آخر يمتلك النطاق المطلوب، أو اطلب من مسؤول مخوّل إنشاء عميل بديل بهذا النطاق ثم حدّث النظام المستهلك. لا تعرض لوحة التحكم الحالية تعديل نطاقات عميل موجود.

404 غير موجود

تعيد إجراءات القوائم والتقارير الحالية عادة مصفوفات فارغة بدل 404. وتعيد نقطة ملف التكامل 404 عندما لا تستطيع تحديد ارتباط ملف إجابة حالي وغير محذوف ومصرح به لمؤسسة المفتاح.

الإجراء: أعد قراءة أوصاف ملفات الاستجابات الخام الحالية واستخدم قيم answerFileId الحالية فقط. لا تتاح الارتباطات المحذوفة أو العابرة للمؤسسات عمدًا، كما تشترط خدمة الملفات بيانات وصفية نشطة للملف.

429 طلبات كثيرة جدا

رفض محدد معدل طلبات مضبوط لواجهة برمجة التكامل الطلب.

تحمي نقاط النهاية سياسات تحديد معدل مسماة. احترم Retry-After عندما يضيفها المحدد المضبوط، ولا تشترط وجودها ما لم تتحقق منها في بيئة النشر:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

الإجراء: نفّذ تراجعًا أسيًا، واحترم Retry-After عند وجودها، وتجنب الاستطلاع عالي التردد.

500 خطأ داخلي في الخادم

حدث خطأ غير متوقع من جانب الخادم.

الإجراء: أعد المحاولة بعد تأخير قصير. إذا استمر الخطأ، أبلغ عن طابع وقت الطلب وأي معلومات ارتباط أعادها النشر فعليًا؛ ولا تضمن وحدات التحكم قيمة traceId.

ملاحظة حول قابلية التكرار

لا تعدل نقاط التكامل بيانات الاستبيانات أو التقارير، لكن كل طلب تنجح مصادقته يحدّث LastUsedAt للعميل ويضيف سجل تدقيق ApiCall قبل فحص النطاق. إعادة المحاولة آمنة لبيانات القراءة لكنها ليست خالية من الآثار التشغيلية.