أكواد أخطاء API

كل كود بيرجع في `error.code` على استدعاء API فاشل، متجمّع حسب المجال. الـ URL بتاع كل إدخال هو قيمة `error.doc_url`.

الصفحة دي هي وجهة كل error.doc_url بتستقبله على استدعاء API فاشل. الإرساء (anchors) هنا بيطابق قيمة code، فـ https://docs.xpay.app/integrate/errors/api-error-codes#parameter_missing بيوصلك مباشرةً للصف اللي تحت.

كل كود متقرن بالـ error.type اللي بيجي معاه. تفرّع على type الأول؛ واستخدم code للحالات الخاصة الضيّقة. للمغلّف وشكل المعالِج، شوف أخطاء API.

الطلب العام

error.type: invalid_request_error. الطلب اترفض بسبب حاجة من ناحيتك. ما تعيدش المحاولة؛ صلّح الطلب.

`invalid_request`

الطلب اترفض ومفيش كود أكثر تحديدًا انطبق. اقرا error.message للتفصيل.

`parameter_missing`

معامل مطلوب كان ناقص من جسم الطلب. error.param بيسمّي الحقل.

`parameter_invalid`

معامل نوعه أو صيغته غلط. error.param بيسمّي الحقل.

`parameter_out_of_range`

قيمة معامل خارج المدى المسموح (مثلًا quantity سالبة أو amount بيتعدّى الحد الأقصى).

`parameter_unknown`

طلبك تضمّن معامل XPay مش بيتعرّف عليه. عادةً خطأ كتابي أو حقل قديم. شيل المعامل المجهول.

`parameters_exclusive`

بعتّ معاملين مينفعش يتستخدموا مع بعض (مثلًا customerId وcustomerDetails على جلسة دفع). اختار واحد.

`parameter_requires_another`

بعتّ معامل بيتطلّب وجود معامل تاني كمان (مثلًا customerUpdate بيتطلّب customerId).

`validation_error`

فشل تحقّق عام ما طابقش أي من الأكواد الأكثر تحديدًا اللي فوق. اقرا error.message.

`resource_missing`

المورد اللي أشرت ليه مش موجود. بيرجع مع HTTP 404. اتأكد من الـ ID ومن إنك بتستخدم المفتاح الصح (اختبار مقابل فعلي).

`resource_invalid_state`

المورد موجود لكن مش في حالة بتسمح بالعملية دي (مثلًا محاولة إنهاء صلاحية جلسة دفع مكتملة بالفعل، أو استرداد عملية دفع ما اتحصّلتش أصلًا).

المصادقة

error.type: authentication_error. HTTP 401. ما تعيدش المحاولة؛ صلّح الاعتماد أو الترويسة.

`authentication_required`

مفيش مفتاح API متقدّم. ترويسة Authorization ناقصة.

`invalid_api_key`

مفتاح الـ API ما طابقش أي مفتاح معروف. الأسباب الشائعة: خطأ كتابي، أو فراغ في الأول/الآخر، أو استخدام مفتاح من حساب تاني.

`api_key_inactive`

مفتاح الـ API اتلاقى لكن معطّل حاليًا. أعِد تفعيله من المطورين ← مفاتيح API في لوحة التحكم، أو استخدم مفتاح تاني.

`invalid_signature`

للنقاط اللي بتتطلّب توقيع HMAC، التوقيع في الطلب ما طابقش القيمة المتوقعة. اتأكد من سرّ التوقيع ومن إنك بتوقّع الجسم القانوني.

التفويض

error.type: invalid_request_error. HTTP 403.

`merchant_not_activated`

حسابك ما خلّصش تفعيل الحساب الفعلي. استدعاءات وضع الاختبار بتشتغل عادي؛ واستدعاءات الحساب الفعلي بترجع ده لحد ما تخلّص الانضمام.

`permission_denied`

مفتاح الـ API أو الجلسة اللي بتستخدمها مالهاش صلاحية للإجراء ده. اتأكد من صلاحيات المفتاح المحدّدة في المطورين ← مفاتيح API.

الجلسات

error.type: invalid_request_error.

`checkout_session_expired`

جلسة الدفع عدّت expiresAt بتاعتها. أنشئ جلسة جديدة لو العميل لسه عايز يدفع.

`invalid_client_secret`

الـ clientSecret ما بيطابقش الجلسة اللي اتقرن بيها. غالبًا معناه إنك لزقت سرّ قديم أو قرنته بمعرّف جلسة غلط.

`creation_failed`

إنشاء الجلسة فشل لسبب غير متوقع. أعِد الطلب؛ ولو استمر، اذكر request_id للدعم.

روابط الدفع

error.type: invalid_request_error.

`payment_link_inactive`

رابط الدفع معطّل ومش هيقبل مدفوعات جديدة. أعِد تفعيله في لوحة التحكم أو اعمل رابط جديد.

`payment_link_expired`

رابط الدفع عدّى تاريخ انتهاء صلاحيته.

المبلغ والعملة

error.type: invalid_request_error.

`amount_invalid`

الـ amount مش قيمة صالحة (سالب، أو صفر حيث المطلوب موجب، أو بيتعدّى الحد الأقصى لكل استدعاء).

`currency_invalid`

كود العملة مش معروف. استخدم كود ISO 4217 من 3 حروف بأحرف صغيرة (مثلًا egp، usd).

الأسعار وبنود الفاتورة

error.type: invalid_request_error. بيرجع لما بند فاتورة يشير لـ Price مينفعش يتستخدم، عند إنشاء جلسة دفع أو عند إنشاء أو تحديث رابط دفع.

`product_archived`

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

بيتطلق من:

PATCH /prices/:id بـ { "active": true }: حاولت تعيد تفعيل سعر منتجه لسه متأرشف. ألغِ أرشفة المنتج الأول، بعدين السعر.
POST /payment-links / PATCH /payment-links/:id: سعر مُشار ليه تابع لمنتج متأرشف. استخدم سعر تحت منتج فعّال.

`price_inactive`

السعر متأرشف (active: false). ده بيحصل يا إما لما التاجر يأرشف السعر مباشرةً، يا إما لما السعر يتأرشف تتابعيًا كجزء من أرشفة المنتج الأب بتاعه. ألغِ أرشفة السعر (أو منتجه الأول، لو المنتج كمان متأرشف)، أو استخدم سعر تاني.

`price_not_yet_active`

السعر ليه startDate في المستقبل ولسه مش فعّال.

`price_expired`

السعر عدّى expirationDate بتاعه.

`price_sold_out`

السعر ليه مخزون محدود وخلص قبل ما العميل يدفع. شيل البند، أو قلّل الكمية المطلوبة، أو أعِد التخزين.

`price_recurring_not_supported`

السعر من نوع RECURRING، اللي مش مقبول في الدفع النهارده. استخدم سعر ONE_TIME.

`price_immutable_while_used`

حاولت تغيّر حقل على سعر اتستخدم في بند فاتورة واحد على الأقل. العملة، والمبلغ، والنوع، وإعدادات recurring بتتقفل بمجرد ما السعر يبقى قيد الاستخدام.

`price_date_range_invalid`

حاولت تحفظ سعر startDate بتاعه في نفس يوم expirationDate أو بعده.

`price_stock_invalid`

حاولت تحفظ سعر بقيمة stock سالبة.

`line_item_missing_price`

بند فاتورة على جلسة دفع اتبعت من غير مرجع price أو كتلة priceData. قدّم واحد.

`checkout_empty_cart`

كل بند على جلسة الدفع كميته 0، يبقى مفيش حاجة تتدفع. ده بيحصل في الطلب اللي كله اختياري لما العميل يحاول يدفع قبل ما يضيف أي بند. ضيف بند واحد على الأقل للطلب، وبعدين ابعت الدفع تاني.

العروض الترويجية والكوبونات

error.type: invalid_request_error.

`promotion_codes_not_allowed`

العميل دخّل كود ترويج على جلسة allowPromotionCodes فيها false.

`promotion_code_not_found`

نص كود الترويج ما بيطابقش أي كود على الحساب ده.

`promotion_code_inactive`

كود الترويج معطّل.

`promotion_code_expired`

كود الترويج عدّى تاريخ انتهاء صلاحيته.

`promotion_code_max_redemptions`

كود الترويج وصل حد الاستخدام العام بتاعه.

`promotion_code_customer_mismatch`

كود الترويج مقيّد لعميل مختلف عن اللي على جلسة الدفع دي.

`promotion_code_minimum_amount`

مبلغ الجلسة ما بيحققش الحد الأدنى للعرض الترويجي.

`promotion_code_first_time_only`

كود الترويج للعملاء لأول مرة بس، والعميل ده دفع قبل كده.

`promotion_code_exists`

حاولت تعمل كود ترويج بنص كود موجود بالفعل. استخدم نص تاني.

`coupon_invalid`

الكوبون غير صالح، أو محذوف، أو منتهي الصلاحية.

`coupon_currency_mismatch`

عملة الكوبون ما بتطابقش عملة الجلسة.

`coupon_minimum_amount`

المجموع الفرعي للجلسة ما بيحققش الحد الأدنى للكوبون.

`coupon_customer_max_redemptions`

العميل وصل حد الاستخدام لكل عميل بتاع الكوبون ده.

`coupon_in_use`

حاولت تحذف كوبون لسه مربوط بكود ترويج أو جلسة نشطة.

`too_many_discounts`

جلسة الدفع تقدر تحمل خصم واحد على الأكتر؛ وإنت حاولت تضيف تاني.

طرق الدفع

error.type: invalid_request_error.

`payment_method_corrupted`

بيانات طريقة الدفع المخزّنة مينفعش تتقرا. خلّي العميل يدخّل بياناته تاني.

`payment_method_customer_mismatch`

طريقة الدفع تخص عميل مختلف عن اللي على الطلب.

`payment_intent_customer_mismatch`

عميل الـ Payment Intent ما بيطابقش العميل اللي بتحاول تتصرف عليه.

`payment_method_mismatch`

نوع طريقة الدفع اللي العميل اختاره مش متضمّن في paymentMethodTypes المسموحة للجلسة.

عمليات الدفع والمبالغ المستردة

error.type: invalid_request_error. بيرجع من POST /refunds وعمليات الـ charge المرتبطة.

`charge_not_captured`

حاولت تسترد عملية دفع ما اتحصّلتش.

`merchant_no_balance`

التاجر مالوش سجل رصيد. اذكر request_id للدعم.

`insufficient_balance`

الاسترداد هيخلّي الرصيد المتاح يبقى سالب.

`charge_missing_balance_transaction`

عملية الدفع ناقصها معاملة الرصيد الأساسية بتاعتها. اذكر request_id للدعم.

`charge_missing_fee_data`

عملية الدفع ناقصها بيانات الرسوم المطلوبة لحساب الاسترداد. اذكر request_id للدعم.

`charge_incomplete_fee_data`

عملية الدفع عندها بيانات رسوم لكنها ناقصة. اذكر request_id للدعم.

تهيئات طرق الدفع

error.type: invalid_request_error.

`cannot_rename_default`

حاولت تعيد تسمية تهيئة طريقة الدفع الافتراضية. أسماء الافتراضية مينفعش تتغير.

`must_have_enabled_method`

التهيئة لازم يبقى فيها طريقة دفع مفعّلة واحدة على الأقل.

`cannot_delete_default`

حاولت تحذف تهيئة طريقة الدفع الافتراضية. خلّي تهيئة تانية هي الافتراضية الأول.

`configuration_in_use`

حاولت تحذف تهيئة مُشار ليها من جلسة دفع نشطة واحدة أو أكتر.

العملة

error.type: invalid_request_error.

`unsupported_currency`

العملة مش مدعومة للتاجر ده أو العملية دي.

`exchange_rate_not_found`

مفيش سعر صرف متظبّط لزوج العملات ده. عرض العملات المتعددة بيتطلّب إن السعر يكون متاح قبل إنشاء الجلسة.

تحديد المعدّل

error.type: rate_limit_error. HTTP 429.

`rate_limit`

حسابك تعدّى حد معدّل الطلبات. تراجَع وأعِد المحاولة بتأخير أسّي.

عدم التكرار (Idempotency)

error.type: idempotency_error. HTTP 400 أو 409. لعقد إعادة المحاولة الكامل، شوف عدم التكرار.

`idempotency_key_in_use`

حالتين بيتشاركوا الكود ده، بيتفرّقوا بحالة الـ HTTP:

400: أعدت استخدام Idempotency-Key مع طلب مختلف (method، أو path، أو query، أو body مختلف). المفتاح مربوط بأول طلب اتستخدم معاه. أعِد استخدام الطلب الأصلي، أو ولّد مفتاح جديد.
409: فيه طلب بالمفتاح ده لسه شغّال. استنى عدد الثواني اللي في ترويسة Retry-After، بعدين أعِد المحاولة. هتاخد نتيجة الطلب الأصلي.

أكواد أخطاء API

أخطاء API

أخطاء الدفع

أكواد أخطاء الدفع

مقدمة الأخطاء

في الصفحة دي