شعار NinjaBuy

تعامل مع عقد استجابات المشكلات واربط الطلبات ببعضها.

تتبع الأخطاء عقد JSON للمشكلات الوارد في RFC 9457، بنوع الوسائط application/problem+json.

{
  "type": "https://www.ninjabuy.com/api/v1/problems/bad-body",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request did not match the expected shape.",
  "request_id": "REQUEST_ID",
  "errors": [{"pointer": "/links", "detail": "Validation detail"}]
}

type هو المعرّف الثابت للمشكلة؛ وtitle وdetail يصفانها. تطابق status حالة HTTP. تحتوي إدخالات errors الاختيارية على JSON Pointer وتفاصيل التحقق؛ والمؤشر الفارغ يعني جسم الطلب بالكامل. اذكر request_id (الموجود أيضًا في X-Request-Id) عند الإبلاغ عن مشكلة.

تبدأ جميع الأنواع أدناه بـ https://www.ninjabuy.com/api/v1/problems/.

لاحقة النوع	HTTP	المعنى / الإجراء
`bad-json`	400	الجسم ليس JSON صالحًا. صحّح صياغته.
`bad-body`	400	فشل الجسم أو معاملات الاستعلام أو المؤشر في التحقق. اقرأ `errors`.
`bad-idempotency-key`	400	استخدم من 1 إلى 255 حرف ASCII قابلًا للطباعة في `Idempotency-Key`.
`unauthorized`	401	قدّم رمز bearer صالحًا؛ يوفّر `WWW-Authenticate` بيانات الاكتشاف.
`not-found`	404	المورد غير متاح أو غير معروف أو لا يملكه هذا الحساب.
`method-not-allowed`	405	استخدم الطريقة المذكورة في `Allow`.
`idempotency-key-in-progress`	409	الطلب الأول بهذا المفتاح قيد التنفيذ. انتظر مدة `Retry-After`.
`upload-too-large`	413	البايتات المرفوعة تتجاوز الحجم المُعلَن أو حد 20 MiB.
`unsupported-media-type`	415	أرسل `Content-Type: application/json`.
`idempotency-key-reused`	422	استُخدم هذا المفتاح مع طلب آخر. استخدم مفتاحًا جديدًا.
`invalid-workbook`	422	الملف المرفوع ليس XLSX/CSV قابلًا للقراءة ضمن الحدود. اقرأ `errors`.
`upload-expired`	422	انتهت صلاحية حجز الرفع. ارفع الملف مرة أخرى.
`rate-limited`	429	انتظر عدد ثواني `Retry-After` قبل إعادة المحاولة.
`search-rate-limited`	429	نافذة البحث بالكلمات المفتاحية ممتلئة. انتظر مدة `Retry-After`.
`service-unavailable`	503	أعد المحاولة بعد قليل؛ والتزم بـ `Retry-After` إن وُجد.
`internal-error`	500	أعد المحاولة لاحقًا؛ واحتفظ بمعرّف الطلب إذا استمرت المشكلة.

قد يحتوي الطلب الناجح مع ذلك على إخفاقات خاصة ببعض المدخلات. تعامل مع حالات الروابط بمعزل عن أخطاء HTTP. استخدم Idempotency-Key لإعادة تنفيذ طلب إنشاء؛ فمن دون مفتاح، تؤدي إعادة محاولة إرسال دفعة إلى إنشاء مهمة أخرى.