# أكواد أخطاء API (/ar/integrate/errors/api-error-codes) كل كود بيرجع في `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](/integrate/errors/api-errors). ## الطلب العام [#الطلب-العام] `error.type`: `invalid_request_error`. الطلب اترفض بسبب حاجة من ناحيتك. ما تعيدش المحاولة؛ صلّح الطلب. ### `invalid_request` [#invalid_request] الطلب اترفض ومفيش كود أكثر تحديدًا انطبق. اقرا `error.message` للتفصيل. ### `parameter_missing` [#parameter_missing] معامل مطلوب كان ناقص من جسم الطلب. `error.param` بيسمّي الحقل. ### `parameter_invalid` [#parameter_invalid] معامل نوعه أو صيغته غلط. `error.param` بيسمّي الحقل. ### `parameter_out_of_range` [#parameter_out_of_range] قيمة معامل خارج المدى المسموح (مثلًا `quantity` سالبة أو `amount` بيتعدّى الحد الأقصى). ### `parameter_unknown` [#parameter_unknown] طلبك تضمّن معامل XPay مش بيتعرّف عليه. عادةً خطأ كتابي أو حقل قديم. شيل المعامل المجهول. ### `parameters_exclusive` [#parameters_exclusive] بعتّ معاملين مينفعش يتستخدموا مع بعض (مثلًا `customerId` و`customerDetails` على جلسة دفع). اختار واحد. ### `parameter_requires_another` [#parameter_requires_another] بعتّ معامل بيتطلّب وجود معامل تاني كمان (مثلًا `customerUpdate` بيتطلّب `customerId`). ### `validation_error` [#validation_error] فشل تحقّق عام ما طابقش أي من الأكواد الأكثر تحديدًا اللي فوق. اقرا `error.message`. ### `resource_missing` [#resource_missing] المورد اللي أشرت ليه مش موجود. بيرجع مع HTTP 404. اتأكد من الـ ID ومن إنك بتستخدم المفتاح الصح (اختبار مقابل فعلي). ### `resource_invalid_state` [#resource_invalid_state] المورد موجود لكن مش في حالة بتسمح بالعملية دي (مثلًا محاولة إنهاء صلاحية جلسة دفع مكتملة بالفعل، أو استرداد عملية دفع ما اتحصّلتش أصلًا). ## المصادقة [#المصادقة] `error.type`: `authentication_error`. HTTP 401. ما تعيدش المحاولة؛ صلّح الاعتماد أو الترويسة. ### `authentication_required` [#authentication_required] مفيش مفتاح API متقدّم. ترويسة `Authorization` ناقصة. ### `invalid_api_key` [#invalid_api_key] مفتاح الـ API ما طابقش أي مفتاح معروف. الأسباب الشائعة: خطأ كتابي، أو فراغ في الأول/الآخر، أو استخدام مفتاح من حساب تاني. ### `api_key_inactive` [#api_key_inactive] مفتاح الـ API اتلاقى لكن معطّل حاليًا. أعِد تفعيله من **المطورين ← مفاتيح API** في لوحة التحكم، أو استخدم مفتاح تاني. ### `invalid_signature` [#invalid_signature] للنقاط اللي بتتطلّب توقيع HMAC، التوقيع في الطلب ما طابقش القيمة المتوقعة. اتأكد من سرّ التوقيع ومن إنك بتوقّع الجسم القانوني. ## التفويض [#التفويض] `error.type`: `invalid_request_error`. HTTP 403. ### `merchant_not_activated` [#merchant_not_activated] حسابك ما خلّصش تفعيل الحساب الفعلي. استدعاءات وضع الاختبار بتشتغل عادي؛ واستدعاءات الحساب الفعلي بترجع ده لحد ما تخلّص الانضمام. ### `permission_denied` [#permission_denied] مفتاح الـ API أو الجلسة اللي بتستخدمها مالهاش صلاحية للإجراء ده. اتأكد من صلاحيات المفتاح المحدّدة في **المطورين ← مفاتيح API**. ### `two_factor_required` [#two_factor_required] إجراء في الوضع المباشر محتاج تحقق ثنائي حديث، والجلسة معملتش تحقق في آخر ٤ ساعات. بيحصل لجلسات لوحة التحكم بس، ومفاتيح الـ API عمرها ما هتشوف الخطأ ده. لوحة التحكم بتتعامل معاه بنفسها: بتطلب كود المصادقة وبتعيد الطلب. ## الجلسات [#الجلسات] `error.type`: `invalid_request_error`. ### `checkout_session_expired` [#checkout_session_expired] جلسة الدفع عدّت `expiresAt` بتاعتها. أنشئ جلسة جديدة لو العميل لسه عايز يدفع. ### `invalid_client_secret` [#invalid_client_secret] الـ `clientSecret` ما بيطابقش الجلسة اللي اتقرن بيها. غالبًا معناه إنك لزقت سرّ قديم أو قرنته بمعرّف جلسة غلط. ### `creation_failed` [#creation_failed] إنشاء الجلسة فشل لسبب غير متوقع. أعِد الطلب؛ ولو استمر، اذكر `request_id` للدعم. ## روابط الدفع [#روابط-الدفع] `error.type`: `invalid_request_error`. ### `payment_link_inactive` [#payment_link_inactive] رابط الدفع معطّل ومش هيقبل مدفوعات جديدة. أعِد تفعيله في لوحة التحكم أو اعمل رابط جديد. ### `payment_link_expired` [#payment_link_expired] رابط الدفع عدّى تاريخ انتهاء صلاحيته. ## المبلغ والعملة [#المبلغ-والعملة] `error.type`: `invalid_request_error`. ### `amount_invalid` [#amount_invalid] الـ `amount` مش قيمة صالحة (سالب، أو صفر حيث المطلوب موجب، أو بيتعدّى الحد الأقصى لكل استدعاء). ### `currency_invalid` [#currency_invalid] كود العملة مش معروف. استخدم كود ISO 4217 من 3 حروف بأحرف صغيرة (مثلًا `egp`، `usd`). ## الأسعار وبنود الفاتورة [#الأسعار-وبنود-الفاتورة] `error.type`: `invalid_request_error`. بيرجع لما بند فاتورة يشير لـ Price مينفعش يتستخدم، عند إنشاء جلسة دفع أو عند إنشاء أو تحديث رابط دفع. ### `product_archived` [#product_archived] المنتج الأب للسعر متأرشف. أرشفة منتج بتنزّل `active: false` على كل أسعاره في معاملة واحدة، فأسعار المنتج المتأرشف مينفعش تتستخدم لحد ما التاجر يلغي أرشفة المنتج. إلغاء الأرشفة باتجاه واحد: إعادة تفعيل المنتج ما بتعيدش تفعيل أسعاره تلقائيًا. كل سعر لازم يتلغى أرشفته صراحةً. بيتطلق من: * `PATCH /prices/:id` بـ `{ "active": true }`: حاولت تعيد تفعيل سعر منتجه لسه متأرشف. ألغِ أرشفة المنتج الأول، بعدين السعر. * `POST /payment-links` / `PATCH /payment-links/:id`: سعر مُشار ليه تابع لمنتج متأرشف. استخدم سعر تحت منتج فعّال. ### `price_inactive` [#price_inactive] السعر متأرشف (`active: false`). ده بيحصل يا إما لما التاجر يأرشف السعر مباشرةً، يا إما لما السعر يتأرشف تتابعيًا كجزء من أرشفة المنتج الأب بتاعه. ألغِ أرشفة السعر (أو منتجه الأول، لو المنتج كمان متأرشف)، أو استخدم سعر تاني. ### `price_not_yet_active` [#price_not_yet_active] السعر ليه `startDate` في المستقبل ولسه مش فعّال. ### `price_expired` [#price_expired] السعر عدّى `expirationDate` بتاعه. ### `price_sold_out` [#price_sold_out] السعر ليه مخزون محدود وخلص قبل ما العميل يدفع. شيل البند، أو قلّل الكمية المطلوبة، أو أعِد التخزين. ### `price_recurring_not_supported` [#price_recurring_not_supported] السعر من نوع `RECURRING`، اللي مش مقبول في الدفع النهارده. هتلاقي نفس الخطأ لو عملت أو عدّلت لينك دفع بيستخدم سعر زي كده. استخدم سعر `ONE_TIME`. ### `price_immutable_while_used` [#price_immutable_while_used] حاولت تغيّر حقل على سعر اتستخدم في بند فاتورة واحد على الأقل. العملة، والمبلغ، والنوع، وإعدادات `recurring` بتتقفل بمجرد ما السعر يبقى قيد الاستخدام. ### `price_date_range_invalid` [#price_date_range_invalid] حاولت تحفظ سعر `startDate` بتاعه في نفس يوم `expirationDate` أو بعده. ### `price_stock_invalid` [#price_stock_invalid] حاولت تحفظ سعر بقيمة `stock` سالبة. ### `line_item_missing_price` [#line_item_missing_price] بند فاتورة على جلسة دفع اتبعت من غير مرجع `price` أو كتلة `priceData`. قدّم واحد. ### `checkout_empty_cart` [#checkout_empty_cart] كل بند على جلسة الدفع كميته 0، يبقى مفيش حاجة تتدفع. ده بيحصل في الطلب اللي كله اختياري لما العميل يحاول يدفع قبل ما يضيف أي بند. ضيف بند واحد على الأقل للطلب، وبعدين ابعت الدفع تاني. ## العروض الترويجية والكوبونات [#العروض-الترويجية-والكوبونات] `error.type`: `invalid_request_error`. ### `promotion_codes_not_allowed` [#promotion_codes_not_allowed] العميل دخّل كود ترويج على جلسة `allowPromotionCodes` فيها `false`. ### `promotion_code_not_found` [#promotion_code_not_found] نص كود الترويج ما بيطابقش أي كود على الحساب ده. ### `promotion_code_inactive` [#promotion_code_inactive] كود الترويج معطّل. ### `promotion_code_expired` [#promotion_code_expired] كود الترويج عدّى تاريخ انتهاء صلاحيته. ### `promotion_code_max_redemptions` [#promotion_code_max_redemptions] كود الترويج وصل حد الاستخدام العام بتاعه. ### `promotion_code_customer_mismatch` [#promotion_code_customer_mismatch] كود الترويج مقيّد لعميل مختلف عن اللي على جلسة الدفع دي. ### `promotion_code_minimum_amount` [#promotion_code_minimum_amount] مبلغ الجلسة ما بيحققش الحد الأدنى للعرض الترويجي. ### `promotion_code_first_time_only` [#promotion_code_first_time_only] كود الترويج للعملاء لأول مرة بس، والعميل ده دفع قبل كده. ### `promotion_code_exists` [#promotion_code_exists] حاولت تعمل كود ترويج بنص كود موجود بالفعل. استخدم نص تاني. ### `coupon_invalid` [#coupon_invalid] الكوبون غير صالح، أو محذوف، أو منتهي الصلاحية. ### `coupon_currency_mismatch` [#coupon_currency_mismatch] عملة الكوبون ما بتطابقش عملة الجلسة. ### `coupon_minimum_amount` [#coupon_minimum_amount] المجموع الفرعي للجلسة ما بيحققش الحد الأدنى للكوبون. ### `coupon_customer_max_redemptions` [#coupon_customer_max_redemptions] العميل وصل حد الاستخدام لكل عميل بتاع الكوبون ده. ### `coupon_in_use` [#coupon_in_use] حاولت تحذف كوبون لسه مربوط بكود ترويج أو جلسة نشطة. ### `too_many_discounts` [#too_many_discounts] جلسة الدفع تقدر تحمل خصم واحد على الأكتر؛ وإنت حاولت تضيف تاني. ## طرق الدفع [#طرق-الدفع] `error.type`: `invalid_request_error`. ### `payment_method_corrupted` [#payment_method_corrupted] بيانات طريقة الدفع المخزّنة مينفعش تتقرا. خلّي العميل يدخّل بياناته تاني. ### `payment_method_customer_mismatch` [#payment_method_customer_mismatch] طريقة الدفع تخص عميل مختلف عن اللي على الطلب. ### `payment_intent_customer_mismatch` [#payment_intent_customer_mismatch] عميل الـ Payment Intent ما بيطابقش العميل اللي بتحاول تتصرف عليه. ### `payment_method_mismatch` [#payment_method_mismatch] نوع طريقة الدفع اللي العميل اختاره مش متضمّن في `paymentMethodTypes` المسموحة للجلسة. ## عمليات الدفع والمبالغ المستردة [#عمليات-الدفع-والمبالغ-المستردة] `error.type`: `invalid_request_error`. بيرجع من `POST /refunds` وعمليات الـ charge المرتبطة. ### `charge_not_captured` [#charge_not_captured] حاولت تسترد عملية دفع ما اتحصّلتش. ### `merchant_no_balance` [#merchant_no_balance] التاجر مالوش سجل رصيد. اذكر `request_id` للدعم. ### `insufficient_balance` [#insufficient_balance] الاسترداد هيخلّي الرصيد المتاح يبقى سالب. ### `charge_missing_balance_transaction` [#charge_missing_balance_transaction] عملية الدفع ناقصها معاملة الرصيد الأساسية بتاعتها. اذكر `request_id` للدعم. ### `charge_missing_fee_data` [#charge_missing_fee_data] عملية الدفع ناقصها بيانات الرسوم المطلوبة لحساب الاسترداد. اذكر `request_id` للدعم. ### `charge_incomplete_fee_data` [#charge_incomplete_fee_data] عملية الدفع عندها بيانات رسوم لكنها ناقصة. اذكر `request_id` للدعم. ## تهيئات طرق الدفع [#تهيئات-طرق-الدفع] `error.type`: `invalid_request_error`. ### `cannot_rename_default` [#cannot_rename_default] حاولت تعيد تسمية تهيئة طريقة الدفع الافتراضية. أسماء الافتراضية مينفعش تتغير. ### `must_have_enabled_method` [#must_have_enabled_method] التهيئة لازم يبقى فيها طريقة دفع مفعّلة واحدة على الأقل. ### `cannot_delete_default` [#cannot_delete_default] حاولت تحذف تهيئة طريقة الدفع الافتراضية. خلّي تهيئة تانية هي الافتراضية الأول. ### `configuration_in_use` [#configuration_in_use] حاولت تحذف تهيئة مُشار ليها من جلسة دفع نشطة واحدة أو أكتر. ## العملة [#العملة] `error.type`: `invalid_request_error`. ### `unsupported_currency` [#unsupported_currency] العملة مش مدعومة للتاجر ده أو العملية دي. ### `exchange_rate_not_found` [#exchange_rate_not_found] مفيش سعر صرف متظبّط لزوج العملات ده. عرض العملات المتعددة بيتطلّب إن السعر يكون متاح قبل إنشاء الجلسة. ## تحديد المعدّل [#تحديد-المعدّل] `error.type`: `rate_limit_error`. HTTP 429. ### `rate_limit` [#rate_limit] حسابك تعدّى حد معدّل الطلبات. تراجَع وأعِد المحاولة بتأخير أسّي. ## عدم التكرار (Idempotency) [#عدم-التكرار-idempotency] `error.type`: `idempotency_error`. HTTP 400 أو 409. لعقد إعادة المحاولة الكامل، شوف [عدم التكرار](/integrate/idempotency). ### `idempotency_key_in_use` [#idempotency_key_in_use] حالتين بيتشاركوا الكود ده، بيتفرّقوا بحالة الـ HTTP: * **`400`**: أعدت استخدام `Idempotency-Key` مع طلب مختلف (method، أو path، أو query، أو body مختلف). المفتاح مربوط بأول طلب اتستخدم معاه. أعِد استخدام الطلب الأصلي، أو ولّد مفتاح جديد. * **`409`**: فيه طلب بالمفتاح ده لسه شغّال. استنى عدد الثواني اللي في ترويسة `Retry-After`، بعدين أعِد المحاولة. هتاخد نتيجة الطلب الأصلي. ## النظام [#النظام] `error.type`: `api_error`. HTTP 500. ### `internal_error` [#internal_error] خطأ غير متوقع من ناحية السيرفر. أعِد المحاولة بتراجع. لو استمر، اذكر `request_id` للدعم. ## رايح فين بعد كده [#رايح-فين-بعد-كده] المغلّف، وأنواع الأخطاء الثلاثة، ونمط المعالِج. المكان التاني: لما بطاقة عميل تفشل، الخطأ بيقعد على `lastPaymentError`، مش في رد HTTP. مرجع `lastPaymentError.code`. أكواد التحقّق من البطاقة، والمعالجة، والاحتيال، والمعالج. رجوع للأول. خريطة المكانين.