الأخطاء والحدود

ما يحمله الرفض

كل رفض هو وصف مشكلة (problem) بصيغة JSON، موقّع:

{
  "type": "https://developers.anis.ly/errors/price-changed",
  "title": "Price changed",
  "status": 409,
  "code": "price_changed",
  "requestId": "01J9R2K8T4V6XQ0M3B7C5D9E1F"
}

• تفرّع بناءً على code. ولا تتفرّع أبدًا بناءً على title أو detail: فهما مكتوبان للبشر، ويتبعان اللغة التي تطلبها (Accept-Language: ar أو en)، وقد تتغيّر صياغتهما.
• type هو عنوان صفحة الرمز — لكل رمز صفحة في رموز الأخطاء، تشرح معناه، وهل اشتُري شيء بطلب الشراء، وما العمل.
• requestId هو ما تذكره حين تسأل أنيس عن استدعاء ما. وهو موجود أيضًا في الترويسة X-Request-Id لكل ردّ.

أمران قد يحملهما الرفض

• Retry-After — حين يعرف أنيس كم يجب الانتظار، بالثواني. التزم به.
• Idempotency-Replayed: true — في طلب الشراء: الردّ المسجَّل لطلب شراء مغلق بالفعل.

حالات رفض تُخفي القاعدة التي أخفقت

بعض حالات الرفض تعطي الردّ نفسه لأسباب مختلفة، عن قصد، حتى لا يُخبر الرفضُ أحدًا أبدًا بما يمكنه الالتفاف عليه:

الحدود

يمكن لموظفي أنيس وضع حدود على تطبيقك، للتطبيق كله أو لكل محفظة على حدة. كل حدّ يعدّ نوعًا واحدًا من الاستدعاءات ضمن نافذة زمنية:

حين يُبلَغ الحدّ، يُرفض الاستدعاء بالرمز rate_limited، مع Retry-After حين يكون وقت إعادة الضبط معروفًا. ويحمي أنيس نفسه أيضًا بحدود لا تعطي وقتًا لإعادة الضبط — فتراجع عندها بفواصل تتزايد أُسّيًّا. الاستدعاء المرفوض لا يسجّل شيئًا: بعد انقضاء الانتظار، أرسله مرة أخرى (ويحتفظ طلب الشراء بمعرّف عمليته).

تبيّن صفحة المسارات والصلاحيات الحدود التي يُحتسب كل استدعاء ضمنها.