أكواد أخطاء 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.
payment_link_inactive
رابط الدفع معطّل ومش هيقبل مدفوعات جديدة. أعِد تفعيله في لوحة التحكم أو اعمل رابط جديد.
payment_link_expired
رابط الدفع عدّى تاريخ انتهاء صلاحيته.
المبلغ والعملة
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 قبل ما تحدد الأقساط، أو شيل الأقساط قبل ما تفتحه.
invoice_link_expired
رابط الفاتورة انتهت صلاحيته. بيرجع مع 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. أعِد المحاولة بتراجع.