الأدلة
الأخطاء والحدود
شكل الاستجابة ورموز الأخطاء وإعادة المحاولة وحدود المعدل.
كل استجابة بصيغة JSON تحتوي ok: true أو false. الاستجابات الناجحة تحمل data (و meta في القوائم)، والفاشلة تحمل message وغالبًا code، و errors لأخطاء التحقق.
{
"ok": false,
"code": "reward_unavailable",
"message": "This reward was already redeemed or is no longer available."
}رموز الأخطاء
| الحالة | الرمز | المعنى |
|---|---|---|
| 422 | — | حقل مفقود أو غير صالح؛ يسرد errors الرسائل لكل حقل. |
| 401 | invalid_api_key | مفتاح API مفقود أو خاطئ أو ملغى. |
| 403 | plan_suspended | مساحة العمل موقوفة حتى تُدفع خطتها. |
| 404 | not_found / reward_not_found | لا يوجد سجل كهذا في مساحة العمل، أو لا توجد مكافأة بهذا الرمز لهذا العميل. |
| 422 | reward_unavailable | المكافأة استُبدلت مسبقًا أو انتهت صلاحيتها أو أُلغيت. |
| 422 | card_not_used_here | برنامج العميل لا يُستخدم في هذا الفرع. |
| 422 | customer_limit_reached | لا تستطيع مساحة العمل استقبال عملاء جدد على خطتها الحالية. |
| 429 | — | طلبات كثيرة جدًا. انتظر ثم أعد المحاولة. |
إعادة المحاولة آمنة
الطلبات متكررة الأمان بحسب مرجعها: الإبلاغ عن الطلب المدفوع نفسه مرتين يكسب مرة واحدة، والإلغاء أو الاسترداد الثاني لا يستعيد شيئًا إضافيًا. استبدال المكافأة نفسها مرتين يعيد reward_unavailable في المرة الثانية. إذا انتهت مهلة الطلب فأرسله مجددًا.
حدود المعدل
يمكن لكل مفتاح API إرسال 120 طلبًا في الدقيقة. بعد ذلك تعيد الواجهة 429 مع ترويسة Retry-After.