أعراف الواجهة — الواجهة البرمجية

الغلاف

كل نجاح يلفّ حمولته داخل data، مع بيانات القوائم في meta إن وُجدت. وكل فشل كائن error فيه code ثابت تقرؤه الآلة، ورسالة للبشر، وdetails اختيارية، وrequestId تذكره عند مراسلة الدعم.

النجاح

{
  "data": { … },
  "meta": { … }
}

الفشل

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "details": { … },
    "requestId": "…"
  }
}

رموز الأخطاء التي ستقابلها

401INVALID_API_KEYمفتاح API غائب أو مجهول أو مُلغى
401UNAUTHENTICATEDلا رمز صالحًا على مسار يتطلبه
403INSUFFICIENT_SCOPEالرمز يفتقد النطاق الذي يعلنه هذا المسار
422VALIDATION_FAILEDالجسم أو الاستعلام لم يجتز التحقق؛ والتفاصيل في details
429RATE_LIMITEDتجاوزت حدّ المفتاح؛ انتظر Retry-After
502UPSTREAM_UNAVAILABLEخدمة خلف الواجهة لم تُجب

حدود الطلبات

تُحسَب الطلبات لكل مفتاح API على نافذة 60 ثانية. الحدّ الافتراضي 120 طلبًا في الدقيقة، ويمكن إصدار مفتاح بحدّ أعلى يصل إلى 10,000. كل استجابة تحمل الترويسات الثلاث أدناه؛ وتجاوز الحدّ يُجاب بـ 429 RATE_LIMITED مع ترويسة Retry-After. انتظر حتى تمضي بدل إعادة المحاولة في حلقة.

على كل استجابة

x-ratelimit-limit: 120
x-ratelimit-remaining: 118
x-ratelimit-reset: 1758854400

ولإتمام الطلب حدوده الأشد فوق ذلك: التسعير وإتمام الطلب مقيّدان لكل سلة ولكل متسوق، والاستجابة المقيَّدة تسمّي البعد الذي تجاوزته.

معرِّفات الطلبات

أرسل X-Request-Id خاصًا بك (حروف وأرقام و._~-، بحدّ 64 حرفًا) فيُعاد على الاستجابة؛ ومن دونه يُخصَّص معرِّف تلقائيًا. وتكرّره الأخطاء داخل الغلاف باسم requestId.

تقسيم الصفحات

قوائم الكتالوج تأخذ معامل page وتُجيب ببيانات القائمة في meta.

الإصدارات

الإصدار في المسار — /v1/…. التغييرات الإضافية (حقول جديدة، مسارات جديدة) تصل في الإصدار الحالي؛ أما الكاسرة فلا تصل إلا في مسار إصدار جديد، ويبقى القديم يعمل ريثما تنتقل التكاملات.