البداية
الأخطاء
كل رفض من الواجهة يأتي في غلاف واحد اسمه PartnerError، برمز ثابت ورسالة بلغتين.
غلاف الخطأ#
{
"code": "SCOPE_REQUIRED",
"message": {
"ar": "هذا المفتاح لا يملك الصلاحية المطلوبة لهذا الطلب.",
"en": "This key lacks the scope this request needs."
},
"field": null,
"retryable": false,
"requestId": "req_01JD7Q8W3K2M",
"detail": {
"required": [
"branches:read"
]
}
}codeثابت لا يتغيّر: ابنِ منطقك عليه.messageللبشر بلغتين، وقد يتغيّر نصه.fieldالحقل المخالف إن وُجد.retryabletrue فقط للرموز 408 و429 و5xx: الطلب نفسه قد ينجح لاحقاً. false: غيّر الطلب أولاً.requestIdرقم الطلب لإرساله إلى الدعم.
رموز الأخطاء#
| الرمز | HTTP | المعنى | إعادة المحاولة |
|---|---|---|---|
UNAUTHENTICATED | 401 | مفتاح الوصول مفقود أو غير صحيح أو ملغى. | لا |
KEY_EXPIRED | 401 | انتهت صلاحية مفتاح الوصول: اطلب مفتاحاً جديداً. | لا |
KEY_ENVIRONMENT_MISMATCH | 401 | هذا المفتاح لبيئة أخرى: مفاتيح الاختبار تعمل على بيئة الاختبار فقط، ومفاتيح الإنتاج على الإنتاج فقط. | لا |
PARTNER_SUSPENDED | 403 | حساب الشريك موقوف مؤقتاً. تواصل مع فريق ليتس بيتزا. | لا |
IP_NOT_ALLOWED | 403 | العنوان الذي جاء منه الطلب غير مسموح لهذا المفتاح. | لا |
SCOPE_REQUIRED | 403 | هذا المفتاح لا يملك الصلاحية المطلوبة لهذا الطلب. | لا |
BRANCH_NOT_ALLOWED | 403 | هذا المفتاح لا يعمل على هذا الفرع. | لا |
RATE_LIMITED | 429 | طلبات كثيرة في وقت قصير. أعد المحاولة بعد المدة المذكورة. | نعم |
INVALID_REQUEST | 400 | الطلب لا يطابق المواصفة. | لا |
INVALID_JSON | 400 | جسم الطلب ليس JSON صالحاً. | لا |
PAYLOAD_TOO_LARGE | 413 | جسم الطلب أكبر من الحد المسموح. | لا |
IDEMPOTENCY_KEY_REQUIRED | 400 | ترويسة Idempotency-Key مطلوبة لهذا الطلب (حتى 128 حرفاً). | لا |
IDEMPOTENCY_KEY_REUSED | 422 | استُخدم مفتاح Idempotency-Key نفسه مع طلب مختلف. | لا |
NOT_FOUND | 404 | غير موجود. | لا |
ORDER_NOT_FOUND | 404 | الطلب غير موجود ضمن طلباتك. | لا |
ACK_CONFLICT | 409 | سبق إقرار الطلب برقم مختلف. | لا |
STATUS_CHANGED | 409 | تغيّرت حالة الطلب منذ قرأتها. اقرأ الطلب ثم أعد الإرسال. | لا |
STATUS_NOT_ALLOWED | 403 | هذه الحالة غير مسموح لك بإرسالها في إعداداتك. | لا |
TRANSITION_NOT_ALLOWED | — | لا يمكن نقل الطلب إلى هذه الحالة من حالته الحالية. | — |
BRANCH_NOT_LIVE | 409 | الربط غير مفعّل بعد في فرع هذا الطلب. | لا |
EVENT_ID_REUSED | 409 | معرّف الحدث eventId مستخدم سابقاً لطلب آخر. | لا |
REASON_REQUIRED | 422 | هذه الحالة تحتاج سبباً: reasonCode أو reasonText. | لا |
CATALOG_SOURCE_REQUIRED | 403 | هذا الشريك ليس مصدر المنيو في إعداداته. | لا |
AVAILABILITY_NOT_ENABLED | 403 | إرسال التوفّر غير مفعّل لهذا الشريك. | لا |
IMPORT_NOT_FOUND | 404 | عملية استيراد المنيو غير موجودة. | لا |
SANDBOX_ONLY | 403 | هذه الأداة تعمل في بيئة الاختبار فقط. | لا |
SANDBOX_QUOTE_INVALID | 422 | تعذّر تسعير الطلب التجريبي: راجع detail.errors (مثلاً الفرع مغلق). | لا |
MAPPINGS_REFUSED | 422 | رُفض طلب الربط كاملاً ولم يتغيّر شيء: راجع detail.errors. | لا |
WEBHOOK_NOT_FOUND | 404 | الاشتراك غير موجود ضمن اشتراكاتك. | لا |
WEBHOOK_INVALID | 422 | بيانات الاشتراك غير صالحة: راجع detail.issues. | لا |
FIELD_REQUIRED | 422 | حقل مطلوب لهذا النوع من الأحداث مفقود. | لا |
CONFLICT | 409 | تعارض مع الحالة الحالية. | لا |
FORBIDDEN | 403 | غير مسموح. | لا |
INTERNAL_ERROR | 500 | خطأ غير متوقع لدينا. أعد المحاولة لاحقاً، وإن تكرر فأرسل رقم الطلب X-Request-Id إلى الدعم. | نعم |
SERVICE_UNAVAILABLE | 503 | الخدمة غير متاحة مؤقتاً. أعد المحاولة لاحقاً. | نعم |
متى تعيد المحاولة#
| الرد | ماذا تفعل |
|---|---|
400 · 404 · 409 · 422 | لا تعد المحاولة. أصلح الطلب أو البيانات أولاً. |
401 · 403 | لا تعد المحاولة. راجع المفتاح وصلاحياته، وأبلغ فريقك. |
429 | انتظر Retry-After ثم أعد المحاولة. |
408 · 5xx · انقطاع | أعد المحاولة بتباعد متزايد (مثلاً 1 ثم 2 ثم 4 ثوانٍ…) بالمفتاح Idempotency-Key نفسه. |