أكواد أخطاء 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`

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

`resource_already_exists`

فيه مورد بنفس القيمة الفريدة موجود بالفعل. بيرجع مع HTTP 409. استخدم الموجود أو اختار قيمة تانية.

`resource_in_use`

المورد مُشار إليه من حاجة تانية ومينفعش يتحذف. بيرجع مع HTTP 409. شيل الإشارات الأول.

المصادقة

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.

`two_factor_required`

إجراء في الوضع المباشر محتاج تحقق ثنائي حديث، والجلسة معملتش تحقق في آخر ٤ ساعات. بيحصل لجلسات لوحة التحكم بس، ومفاتيح الـ API عمرها ما هتشوف الخطأ ده. لوحة التحكم بتتعامل معاه بنفسها: بتطلب كود المصادقة وبتعيد الطلب.

الجلسات

error.type: invalid_request_error.

`checkout_session_expired`

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

`invalid_client_secret`

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

`amount_reconfirmation_required`

إجمالي الجلسة اللي بيشوفه العميل ما بيطابقش المبلغ اللي اتعرض له، فالطلب اترفض ومفيش أي مبلغ اتخصم. اعرض الإجمالي الحالي وأكّد تاني. بيحصل مع Elements المؤجّلة لما الجلسة اللي السيرفر بتاعك أنشأها وقت الدفع إجماليها مختلف عن اللي الـ element عرضه. شوف Elements: الوضع المؤجّل.

`creation_failed`

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

`payment_still_confirming`

العميل حاول يدفع تاني والمحاولة السابقة على الجلسة دي لسه بيتأكّد منها. بيرجع مع HTTP 409. استنى لحظة وأعِد المحاولة؛ العميل عمره ما هيتخصم منه مرتين.

`payment_already_completed`

المحاولة السابقة على الجلسة دي طلعت ناجحة، فإعادة المحاولة اترفضت. بيرجع مع HTTP 409. الجلسة مدفوعة. اقراها علشان تاخد النتيجة، وما تطلبش من العميل يدفع تاني.

روابط الدفع

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. قدّم واحد.

`line_item_quantity_not_adjustable`

تحديث كمية على POST /checkout/sessions/:id/update استهدف بند كميته ثابتة (adjustableQuantity مش مفعّل). البنود الثابتة العميل مش بيقدر يغيّرها — أنشئ الجلسة بـ adjustableQuantity.enabled: true على البنود اللي المفروض تقبل تغيير الكمية.

`line_item_quantity_out_of_bounds`

الكمية المطلوبة خارج حدود adjustableQuantity.minimum / maximum المضبوطة للبند. ابعت كمية جوّه الحدود؛ minimum بقيمة 0 معناها إن البند اختياري وممكن يتشال.

`line_item_quantity_not_supported_for_custom`

تحديث كمية استهدف بند من نوع CUSTOM. البنود المخصصة كميتها دايمًا 1 والمبلغ فيها بيدخله العميل — ابعت customAmount لتغيير المبلغ.

`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

أخطاء الدفع

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

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

في الصفحة دي