الأخطاء ومعرفات الطلب

طبقات الخطأ

أخطاء النقل تعني أن الاتصال لم يكتمل، ولا تثبت أن العملية لم تنفذ. أخطاء HTTP تعني أن الخادم استجاب، بينما يوضح جسم JSON الرمز والرسالة وحقول التحقق. افصل هذه الطبقات في مكتبة العميل.

الرموز المهمة

400 لطلب غير صالح بنيويًا أو غياب محدد النشاط، و401 لمشكلة اعتماد، و403 لنطاق غير مسموح، و404 لمورد غير موجود، و409 لتعارض منع التكرار أو انتقال حالة، و422 للتحقق أو قرار التحكم، و429 لتجاوز الحد. لا تحول جميعها إلى رسالة واحدة ولا تعيد كل الحالات تلقائيًا.

Request ID

أنشئ X-Request-ID فريدًا لكل محاولة نقل، واحتفظ بمعرف النية أو idempotency منفصلًا. Request ID يربط سجلك بسجل LuxPay، أما مفتاح منع التكرار فيربط عدة محاولات بالعملية نفسها. لا تضع بيانات شخصية أو أسرارًا داخل المعرف.

رسائل المستخدم

اعرض رسالة آمنة ومفهومة للمستخدم، وسجل الرمز التقني ومعرف الطلب داخليًا. لا تعرض Stack Trace أو تفاصيل قاعدة البيانات. عند الاتصال بالدعم أرسل الوقت، البيئة، operationId، Request ID، معرف المورد وحالة HTTP، دون إرسال الرمز أو كلمة المرور.

شكل الأخطاء

بسبب وجود مسارين تاريخيين للاستجابة قد ترى success: false أو status: false. مكتبة العميل يجب أن تعتمد على HTTP status أولًا ثم تقرأ الحقول المتاحة بدل افتراض Envelope واحد في كل المسارات.