أكواد الأخطاء وحالات HTTP

يعيد كل إخفاق كودًا ثابتًا يقرأه الحاسوب إلى جانب حالة HTTP. تفرّع على الكود، لا على نصّ الرسالة أبدًا: الرسائل مكتوبة للبشر وقد يُعاد صياغتها، أما الأكواد فجزء من العقد.

كل الأكواد الـ 42 التي يمكن أن تعيدها واجهة الموزّعين البرمجية، مصنَّفة حسب سبب الخطأ. كل مدخل يذكر حالة HTTP التي يصل بها والتغيير الذي يحلّه.

المصادقة (401)

الكود	HTTP	ماذا يعني	كيف تحلّه
MISSING_API_KEY	401	مفتاح API مطلوبلم تُرسَل ترويسة Authorization، أو أن صيغتها غير صحيحة.	أضف الترويسة: Authorization: Bearer <keyId>.<secret>action: FIX_INPUT · retryable: false · retry_after: null
INVALID_API_KEY	401	مفتاح API غير صالحمفتاح API المرسل لا يطابق أي مفتاح نشط في النظام.	تأكد من صحة معرّف المفتاح والسر. وعند الحاجة، أعد توليد المفتاح من لوحة الوصول إلى API.action: FIX_INPUT · retryable: false · retry_after: null

الصلاحيات (403)

الكود	HTTP	ماذا يعني	كيف تحلّه
ACCOUNT_DISABLED	403	الحساب معطّللم يعد هذا الخطأ يُرجَع. أي حساب لا يمكنه إنشاء طلبات يتلقى الرد ACCOUNT_FROZEN (HTTP 403).	تعامل مع رمز الخطأ ACCOUNT_FROZEN بدلاً من هذا الرمز.لم تعد الواجهة تُرجعه، وحلّ محله ACCOUNT_FROZEN
ACCOUNT_FROZEN	403	الحساب مجمّدجُمّد حسابك مؤقتاً، وغالباً ما يكون السبب نشاطاً مريباً.	تواصل مع الدعم لإلغاء تجميد حسابك.action: CONTACT_SUPPORT · retryable: false · retry_after: null
IP_NOT_ALLOWED	403	عنوان IP غير موجود في قائمة السماحصدر الاستدعاء من عنوان IP غير مدرج في قائمة السماح الخاصة بمفتاح API.	أضف عنوان IP لخادمك إلى قائمة السماح من لوحة الوصول إلى API، أو ألغِ قيود IP.action: FIX_INPUT · retryable: false · retry_after: null

التحقق من الطلب (400)

الكود	HTTP	ماذا يعني	كيف تحلّه
MISSING_REQUIRED_FIELD	400	حقل مطلوب مفقودأحد الحقول المطلوبة غير موجود في جسم الطلب. في متطلبات اللاعب، يحدد details.field اسم الحقل المفقود.	راجع توثيق نقطة الوصول، وراجع GET /catalog/category/:categoryId/requirements لمعرفة حقول اللاعب، ثم أرسل كل الحقول المطلوبة.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_FORMAT	400	صيغة أحد المعاملات غير صالحةأحد حقول المتطلبات بصيغة خاطئة (مثل نص في حقل رقمي). يحدد details.field اسم الحقل.	راجع متطلبات الفئة مجدداً، وأرسل الحقل بالصيغة التي يتوقعها data_type الخاص به وقواعد التحقق.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_VALUE	400	قيمة أحد المعاملات غير صالحةقيمة أحد حقول المتطلبات خارج النطاق المسموح (أقل من الحد الأدنى، أو أكبر من الحد الأقصى، أو ليست ضمن select_options الخاصة به). يحدد details.field اسم الحقل.	أرسل قيمة تسمح بها متطلبات الفئة لهذا الحقل.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PARAMETER_LENGTH	400	طول أحد المعاملات غير صالحقيمة أحد الحقول المطلوبة أقصر أو أطول من الحد المسموح. يذكر details.field اسم هذا الحقل.	راجع الحدين الأدنى والأقصى للطول (min_length و max_length) في متطلبات الفئة.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_UUID_FORMAT	400	صيغة UUID غير صالحةقيمة order_id ليست بصيغة UUID صالحة.	استخدم أي إصدار صالح من معرّف UUID، مثل v1 أو v4 أو v7 أو غيرها من الإصدارات. ويجب أن يأتي المعرّف على الشكل التالي: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_QUANTITY	400	الكمية غير صالحةيجب أن تكون الكمية عدداً صحيحاً موجباً.	أرسل الكمية عدداً صحيحاً >= 1.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_CATEGORY_ID	400	معرّف الفئة غير صالحقيمة categoryId المرسلة ليست رقماً صالحاً.	استخدم مستكشف الكتالوج أو GET /catalog/categories للعثور على معرّفات فئات صالحة.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_BIG_CATEGORY_ID	400	معرّف الفئة الرئيسية غير صالحقيمة bigCategoryId المرسلة ليست رقماً صالحاً.	ابحث عن معرّفات الفئات الرئيسية الصالحة عبر مستكشف الكتالوج أو GET /catalog/big-categories.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_ITEM_ID	400	معرّف العنصر غير صالحمعرّف العنصر المرسل غير صالح.	تجد معرّفات العناصر الصالحة في مستكشف الكتالوج أو عبر GET /catalog/subcategories.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_SUBCATEGORY	400	الفئة الفرعية غير صالحةمعرّف الفئة الفرعية غير موجود.	تحقّق من sub_category_id عبر نقاط نهاية الكتالوج.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_PRODUCT_CONFIG	400	إعدادات المنتج غير صالحةلم يعد هذا الرمز يُرسَل. عند نقص حقل مطلوب يصلك الآن MISSING_REQUIRED_FIELD، وعند تعذّر بيع المنتج حالياً يصلك PRODUCT_UNAVAILABLE.	استبدل معالجتك لهذه الاستجابة بالاستجابتين البديلتين MISSING_REQUIRED_FIELD و PRODUCT_UNAVAILABLE في تطبيقاتك.لم تعد الواجهة تُرجعه، وحلّ محله MISSING_REQUIRED_FIELD
INVALID_PAGINATION	400	معاملات ترقيم الصفحات غير صالحةقيمة page أو limit خارج النطاق المسموح.	اجعل قيمة page لا تقل عن 1، وقيمة limit بين 1 و 100.action: FIX_INPUT · retryable: false · retry_after: null
INVALID_DATE_FORMAT	400	صيغة التاريخ غير صالحةالقيمة المرسلة في أحد المعاملين created_after أو created_before لا تمثل تاريخاً صالحاً وفق معيار ISO 8601.	اكتب التاريخ بصيغة ISO 8601: 2024-01-01T00:00:00Z.action: FIX_INPUT · retryable: false · retry_after: null

التحقق من اللاعب (400 / 429 / 503)

الكود	HTTP	ماذا يعني	كيف تحلّه
PLAYER_NOT_FOUND	400	اللاعب غير موجودأكدت اللعبة أن معرّف اللاعب هذا غير موجود. لا يُرسَل هذا الرمز إلا بعد تأكيد صريح، أما إذا تعذّر التحقق من المعرّف فيصلك PLAYER_CHECK_UNAVAILABLE.	تأكد من صحة معرّف اللاعب، وتحقق مما إذا كانت اللعبة تتطلب zone_id.action: FIX_INPUT · retryable: false · retry_after: null
PLAYER_CHECK_UNAVAILABLE	503	يتعذّر التحقق من معرّفات اللاعبين لهذه اللعبة حالياًلا يمكن فحص معرّفات اللاعبين في هذه اللعبة في الوقت الحالي. معرّف اللاعب لم يُرفض.	كرّر الطلب نفسه بعد retry_after ثانية. لا تخبر عميلك بأن المعرّف خاطئ.action: RETRY_LATER · retryable: true · retry_after: 60
PLAYER_BUSY	429	يجري التحقق من معرّف اللاعب هذا بالفعلما زال طلب آخر لمعرّف اللاعب نفسه قيد التحقق.	أرسل الطلب مرة أخرى بعد retry_after ثانية.action: RETRY_SOON · retryable: true · retry_after: 5
PLAYER_VALIDATION_FAILED	400	فشل التحقق من اللاعبلم يعد هذا الرمز يُرسَل. إذا تعذّر التحقق من معرّف اللاعب حالياً يصلك PLAYER_CHECK_UNAVAILABLE (HTTP 503).	تعامل في تطبيقك مع الرمز PLAYER_CHECK_UNAVAILABLE بدلاً من هذا الرمز.لم تعد الواجهة تُرجعه، وحلّ محله PLAYER_CHECK_UNAVAILABLE
REGION_MISMATCH	400	لا يمكن لمنطقة هذا اللاعب استلام هذا المنتجينتمي اللاعب إلى منطقة لا يمكن توصيل هذا المنتج إليها. يتضمن الخطأ الحقلين player_region و player_name.	اختر المنتج المخصص لمنطقة اللاعب.action: CHOOSE_OTHER · retryable: false · retry_after: null

قواعد العمل (400 / 409)

الكود	HTTP	ماذا يعني	كيف تحلّه
INSUFFICIENT_BALANCE	400	رصيد المحفظة غير كافٍلا يكفي رصيد محفظتك لإتمام هذا الطلب.	اشحن محفظتك من صفحة الشحن قبل تقديم الطلب.action: TOP_UP · retryable: false · retry_after: null
OUT_OF_STOCK	400	نفد مخزون المنتجالمنتج المطلوب غير متوفر في المخزون حالياً.	حاول لاحقاً أو اختر منتجاً آخر.action: RETRY_LATER · retryable: true · retry_after: null
INSUFFICIENT_STOCK	400	الوحدات المتوفرة أقل من الكمية المطلوبةعدد الوحدات المتوفرة أقل مما طلبته. بخلاف OUT_OF_STOCK، يمكنك معالجة هذا الخطأ: يحدد error.max_quantity عدد الوحدات التي يمكن طلبها الآن. لم يُخصم أي مبلغ.	أعد إرسال الطلب بكمية تساوي error.max_quantity أو أقل.action: FIX_INPUT · retryable: false · retry_after: null
PRODUCT_UNAVAILABLE	409	هذا المنتج غير متاح مؤقتاًالمنتج موجود لكن لا يمكن بيعه حالياً.	أعد المحاولة لاحقاً، أو اختر منتجاً مختلفاً.action: RETRY_LATER · retryable: true · retry_after: null
PRICING_UPDATING	409	يجري تحديث سعر المنتجسعر هذا المنتج قيد التحديث الآن.	أرسل الطلب نفسه مجدداً بعد retry_after ثانية، ثم راجع السعر من جديد.action: RETRY_SOON · retryable: true · retry_after: 30
OFFER_NOT_FOUND	400	هذا العرض غير متاح لحساب هذا اللاعبالعرض المتاح لمرة واحدة فقط (مثل مكافأة أول شحن) غير متوفر لحساب هذا اللاعب، وربما استُخدم من قبل.	اختر منتجاً آخر لهذا اللاعب.action: CHOOSE_OTHER · retryable: false · retry_after: null
DUPLICATE_ORDER	409	معرّف الطلب مكرريوجد طلب سابق بهذا المعرّف UUID. هذه حماية تمنع تنفيذ الطلب نفسه مرتين.	أنشئ UUID جديداً لكل طلب جديد. إذا ظهر هذا الخطأ عند إعادة المحاولة فالمحاولة الأولى قد سُجّلت: اطّلع على ذلك الطلب عبر GET /orders/{orderId} بدلاً من إنشاء طلب آخر.action: CHECK_ORDER · retryable: false · retry_after: null
PRICE_INCREASED	400	ارتفع السعر عن المتوقعسعر الوحدة الحالي أعلى من قيمة expected_unit_price التي أرسلتها.	احصل على السعر الحالي للمنتج من المسار GET /catalog/subcategory/:id/price، ثم حدّث سعر الوحدة المتوقع في الحقل expected_unit_price داخل طلب الشراء ليساوي هذا السعر.action: FIX_INPUT · retryable: false · retry_after: null
SUBCATEGORY_DISABLED	400	الفئة الفرعية معطّلةلم يعد هذا الخطأ يُرسَل. المنتج الذي لا يمكن بيعه حالياً يُرجع PRODUCT_UNAVAILABLE (HTTP 409).	تعامل مع رمز الخطأ PRODUCT_UNAVAILABLE بدلاً من هذا الرمز.لم تعد الواجهة تُرجعه، وحلّ محله PRODUCT_UNAVAILABLE

غير موجود (404)

الكود	HTTP	ماذا يعني	كيف تحلّه
ORDER_NOT_FOUND	404	الطلب غير موجودلا يوجد طلب بالمعرّف المرسَل.	تأكد من صحة معرّف الطلب.action: FIX_INPUT · retryable: false · retry_after: null
ITEM_NOT_FOUND	404	العنصر غير موجودلا يحتوي الكتالوج على العنصر المطلوب.	استخدم نقاط نهاية الكتالوج للعثور على معرّفات عناصر صحيحة.action: FIX_INPUT · retryable: false · retry_after: null
NO_REQUIREMENTS_FOUND	404	لا توجد متطلبات لهذه الفئةلا تملك هذه الفئة حالياً متطلبات لاعب يمكن إرجاعها.	حاول مرة أخرى لاحقاً أو اختر فئة أخرى.action: RETRY_LATER · retryable: true · retry_after: null
ITEM_NOT_AVAILABLE	404	العنصر غير متاحلم يعد هذا الخطأ يُرسَل. العنصر الموجود الذي لا يمكن بيعه حالياً يُرجع PRODUCT_UNAVAILABLE (HTTP 409).	تعامل مع رمز الخطأ PRODUCT_UNAVAILABLE بدلاً من هذا الرمز.لم تعد الواجهة تُرجعه، وحلّ محله PRODUCT_UNAVAILABLE

التحقق من الطلبات المجمّعة (400)

الكود	HTTP	ماذا يعني	كيف تحلّه
INVALID_ORDER_IDS_FORMAT	400	صيغة order_ids غير صحيحةيجب أن يكون الحقل order_ids مصفوفة من النصوص.	أرسل order_ids بهذا الشكل: { "order_ids": ["uuid1", "uuid2"] }.action: FIX_INPUT · retryable: false · retry_after: null
EMPTY_ORDER_IDS	400	مصفوفة المعرّفات order_ids فارغةلا يمكن أن تكون مصفوفة order_ids فارغة.	أضف معرّف طلب واحداً على الأقل إلى المصفوفة.action: FIX_INPUT · retryable: false · retry_after: null
TOO_MANY_ORDER_IDS	400	عدد معرّفات الطلبات كبير جداًيمكن الاستعلام عن 50 معرّف طلب كحد أقصى في المرة الواحدة.	قسّم طلبك إلى دفعات لا تتجاوز كل منها 50 معرّفاً.action: FIX_INPUT · retryable: false · retry_after: null

حد معدل الطلبات (429)

الكود	HTTP	ماذا يعني	كيف تحلّه
RATE_LIMIT_EXCEEDED	429	تم تجاوز حد الطلباتلقد تجاوزت عدد الاستدعاءات المسموح به لهذا المسار. مجموعات الحدود التي تُحتسب بالدقيقة، وهي مسارات الكتالوج والطلبات والحساب، ترسل الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset مع كل استجابة تصلك، ويكرر الحقل details القيم limit وremaining (وتكون قيمتها 0) وretry_after وwindow_seconds. أما المسار POST /player/validate فيُحتسب استهلاكه من حصتك اليومية من عمليات التحقق من اللاعبين، ولذلك لا يرسل هذه الترويسات، ويحمل رد الخطأ 429 الخاص به القيم limit وcurrent وremaining وreset_at وreset_in_seconds داخل الكائن error. وفي كلتا الحالتين يحدد الحقل error.retry_after والترويسة Retry-After عدد الثواني التي عليك انتظارها.	انتظر عدد الثواني المذكور في retry_after أو في ترويسة Retry-After قبل إعادة المحاولة. وفي نقاط النهاية ذات الحصة بالدقيقة، راقب X-RateLimit-Remaining حتى لا تبلغ الحد أصلاً.action: RETRY_LATER · retryable: true · retry_after: ثانية حتى إعادة التعيين

أخطاء الخادم (5xx)

الكود	HTTP	ماذا يعني	كيف تحلّه
INTERNAL_ERROR	500	خطأ داخلي في الخادمحدث خطأ غير متوقع في الخادم.	أعد إرسال الطلب بعد مرور retry_after ثانية. ومع POST /orders/create استخدم قيمة order_id نفسها، فلا يمكن عندها أن يُنشأ الطلب مرتين. إذا استمر الخطأ فتواصل مع الدعم.action: RETRY_LATER · retryable: true · retry_after: 30
SERVICE_UNAVAILABLE	503	الخدمة غير متاحة مؤقتاًلم يعد هذا الخطأ يُرسَل. أي عطل من جهة الخادم يُرجع INTERNAL_ERROR (HTTP 500)؛ والرمز 503 الوحيد هو PLAYER_CHECK_UNAVAILABLE عندما يتعذر التحقق من معرّف اللاعب في الوقت الحالي.	استبدل معالجتك لهذه الاستجابة بالاستجابتين البديلتين INTERNAL_ERROR و PLAYER_CHECK_UNAVAILABLE في تطبيقك.لم تعد الواجهة تُرجعه، وحلّ محله INTERNAL_ERROR

جديد على المنصة؟ ابدأ من نظرة عامة على واجهة شحن الألعاب للموزّعين، أو اقرأ نظرة عامة على برنامج موزّعي SHOP2TOPUP لمعرفة كيفية عمل حساب الشريك.