التوثيق
الدمجالأخطاء

أكواد أخطاء 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 بتاعتها، أو اتنهت. أنشئ جلسة جديدة لو العميل لسه عايز يدفع.

checkout_session_complete

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

invalid_client_secret

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

livemode_mismatch

المفتاح العام وجلسة الدفع (أو رابط الدفع) في وضعين مختلفين، زي إنك تستخدم مفتاح pk_test_ مع جلسة cs_live_. بيرجع مع HTTP 400. استخدم المفتاح العام اللي من نفس وضع المفتاح السري اللي أنشأ الجلسة: pk_live_ مع sk_live_، وpk_test_ مع sk_test_.

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.

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

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

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

error.type: invalid_request_error.

amount_invalid

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

amount_too_small

المبلغ أقل من الحد الأدنى اللي طريقة الدفع المختارة بتقبله. العميل يقدر يختار طريقة دفع تانية.

amount_too_large

المبلغ أكبر من الحد الأقصى اللي طريقة الدفع المختارة بتقبله. العميل يقدر يختار طريقة دفع تانية.

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

مبلغ الجلسة ما بيحققش الحد الأدنى للعرض الترويجي. error.minimum_amount فيه الحد الأدنى، بأصغر وحدة من العملة اللي العميل بيدفع بيها.

promotion_code_first_time_only

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

promotion_code_exists

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

coupon_invalid

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

coupon_currency_mismatch

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

coupon_minimum_amount

المجموع الفرعي للجلسة ما بيحققش الحد الأدنى للكوبون. error.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 المسموحة للجلسة.

payment_method_not_available

طريقة الدفع مش مفعّلة في صفحة الدفع دي. العميل يقدر يختار طريقة دفع تانية.

payment_intent_unexpected_state

الـ Payment Intent اتعالج بالفعل، أو في حالة ما بتسمحش بالإجراء ده. اقرا حالة الدفع لجلسة الدفع قبل ما تحاول تاني.

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

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

charge_not_captured

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

merchant_no_balance

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

insufficient_balance

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

refund_outcome_unconfirmed

فيه استرداد قبل كده على عملية الدفع دي ممكن يكون رجّع الفلوس فعلًا، فاسترداد جديد ممكن يرجّع للعميل مرتين وعشان كده ما اتبعتش. كلّم دعم XPay برقم عملية الدفع يحسموه قبل ما تسترد تاني.

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: invalid_request_error.

tax_rate_archived

نسبة الضريبة مؤرشفة، فمينفعش تتضاف لفاتورة. استعدها أو استخدم نسبة تانية.

الفواتير

error.type: invalid_request_error. بترجع من نقاط الفواتير ودفعات الفواتير والإشعارات الدائنة. علشان تعرف الخطوات، شوف الفواتير.

invoice_not_editable

الحقل ده مينفعش يتغير والفاتورة في حالتها الحالية. الفاتورة الصادرة بتتصحح بإشعار دائن أو بنسخة جديدة.

invoice_not_finalizable

الفاتورة ناقصها حاجة لازمة قبل ما تصدر، زي تاريخ استحقاق صحيح أو إجمالي مش بالسالب.

invoice_not_open

الإجراء محتاج فاتورة مفتوحة، والفاتورة دي في حالة تانية.

invoice_no_lines

الفاتورة مفيهاش بنود. ضيف بند واحد على الأقل قبل الإصدار.

invoice_customer_incomplete

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

invoice_already_paid

الفاتورة مدفوعة بالكامل بالفعل. علشان ترجّع فلوس، أصدر إشعار دائن.

invoice_voided

الفاتورة اتلغت ومبقاش ينفع تتدفع أو تتغير.

invoice_has_payments

الإجراء مرفوض علشان فيه دفعة اتستلمت على الفاتورة. أصدر إشعار دائن بدل ما تلغيها أو تعدّلها.

invoice_payment_in_progress

فيه دفعة أونلاين تانية على الفاتورة دي لسه شغّالة. بيرجع مع HTTP 409. حاول تاني لما تخلص.

invoice_amount_not_supported

لا توجد وسيلة دفع على الفاتورة تقبل هذا المبلغ. ادفع مبلغًا مختلفًا، أو اطلب من النشاط التجاري إتاحة وسيلة دفع أخرى.

invoice_online_payment_unavailable

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

invoice_partial_payment_not_allowed

الفاتورة مش بتقبل الدفع الجزئي. لازم تتدفع بالكامل، أو بالقسط لو ليها خطة دفع.

invoice_partial_amount_invalid

المبلغ الجزئي أقل من الحد الأدنى، أو أكبر من المتبقي، أو بيسيب أقل من الحد الأدنى للدفع بعدين.

invoice_installments_mismatch

مجموع مبالغ الأقساط مش بيساوي اللي الخطة لازم تغطّيه: الـ total على المسودة، أو amountDue ناقص الإشعارات الدائنة على فاتورة اتعملها finalize.

invoice_plan_with_part_payments

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

رابط الفاتورة انتهت صلاحيته. بيرجع مع HTTP 410. اعمل رابط جديد عن طريق POST /invoices/:id/rotate-link.

invoice_currency_mismatch

فيه بند أو كوبون أو سعر بعملة مختلفة عن عملة الفاتورة.

invoice_line_limit_exceeded

عدد بنود الفاتورة أكبر من المسموح. الحد 250 بند.

invoice_number_taken

رقم الفاتورة ده مستخدم في فاتورة تانية.

credit_note_amount_too_large

قيمة الإشعار الدائن أكبر من اللي لسه ينفع يتخصم من الفاتورة.

credit_note_split_mismatch

مجموع refundAmount وcreditAmount وoutOfBandAmount مش بيساوي الجزء المدفوع بالفعل من الإشعار الدائن.

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

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، بعدين أعِد المحاولة. هتاخد نتيجة الطلب الأصلي.

النظام

error.type: api_error. HTTP 500.

internal_error

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

request_timeout

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

رايح فين بعد كده

في الصفحة دي

الطلب العامinvalid_requestparameter_missingparameter_invalidparameter_out_of_rangeparameter_unknownparameters_exclusiveparameter_requires_anothervalidation_errorresource_missingresource_invalid_stateresource_already_existsresource_in_useالمصادقةauthentication_requiredinvalid_api_keyapi_key_inactiveinvalid_signatureالتفويضmerchant_not_activatedpermission_deniedtwo_factor_requiredالجلساتcheckout_session_expiredcheckout_session_completeinvalid_client_secretlivemode_mismatchamount_reconfirmation_requiredcreation_failedpayment_still_confirmingpayment_already_completedروابط الدفعpayment_link_inactivepayment_link_expiredالمبلغ والعملةamount_invalidamount_too_smallamount_too_largecurrency_invalidالأسعار وبنود الفاتورةproduct_archivedprice_inactiveprice_not_yet_activeprice_expiredprice_sold_outprice_recurring_not_supportedprice_immutable_while_usedprice_date_range_invalidprice_stock_invalidline_item_missing_priceline_item_quantity_not_adjustableline_item_quantity_out_of_boundsline_item_quantity_not_supported_for_customcheckout_empty_cartالعروض الترويجية والكوبوناتpromotion_codes_not_allowedpromotion_code_not_foundpromotion_code_inactivepromotion_code_expiredpromotion_code_max_redemptionspromotion_code_customer_mismatchpromotion_code_minimum_amountpromotion_code_first_time_onlypromotion_code_existscoupon_invalidcoupon_currency_mismatchcoupon_minimum_amountcoupon_customer_max_redemptionscoupon_in_usetoo_many_discountsطرق الدفعpayment_method_corruptedpayment_method_customer_mismatchpayment_intent_customer_mismatchpayment_method_mismatchpayment_method_not_availablepayment_intent_unexpected_stateعمليات الدفع والمبالغ المستردةcharge_not_capturedmerchant_no_balanceinsufficient_balancerefund_outcome_unconfirmedcharge_missing_balance_transactioncharge_missing_fee_datacharge_incomplete_fee_dataتهيئات طرق الدفعcannot_rename_defaultmust_have_enabled_methodcannot_delete_defaultconfiguration_in_useالعملةunsupported_currencyexchange_rate_not_foundنسب الضريبةtax_rate_archivedالفواتيرinvoice_not_editableinvoice_not_finalizableinvoice_not_openinvoice_no_linesinvoice_customer_incompleteinvoice_already_paidinvoice_voidedinvoice_has_paymentsinvoice_payment_in_progressinvoice_amount_not_supportedinvoice_online_payment_unavailableinvoice_partial_payment_not_allowedinvoice_partial_amount_invalidinvoice_installments_mismatchinvoice_plan_with_part_paymentsinvoice_link_expiredinvoice_currency_mismatchinvoice_line_limit_exceededinvoice_number_takencredit_note_amount_too_largecredit_note_split_mismatchتحديد المعدّلrate_limitعدم التكرار (Idempotency)idempotency_key_in_useالنظامinternal_errorrequest_timeoutرايح فين بعد كده