# مقدمة (/ar/integrate/errors/introduction)

XPay بيوضّح حالات الفشل في مكانين مختلفين: جسم رد استدعاء API عملته، وحقل lastPaymentError على عملية دفع فشلت. اختار المكان اللي يناسب مشكلتك.

XPay بيوضّح حالات الفشل في **مكانين مختلفين**، والاتنين بيتعاملوا بنمطين مختلفين. اختار اللي يناسب اللي حصل دلوقتي:

* **استدعاء API عمله السيرفر بتاعك رجّع رد غير 2xx**. الخطأ في جسم رد الـ HTTP. بتتعامل معاه في المكان اللي الاستدعاء بيحصل فيه. ← [أخطاء API](/integrate/errors/api-errors).
* **عملية دفع لعميل فشلت**. الخطأ بيقعد على حقل `lastPaymentError` بتاع الـ Payment Intent لباقي عمره. بتقراه بعد محاولة الدفع، في معالِج الـ webhook بتاعك أو في لوحة التحكم. ← [أخطاء الدفع](/integrate/errors/payment-errors).

المكانين دول مش بيتشاركوا في قائمة أكواد ومش بيتشاركوا في مساحة عناوين URL للتوثيق. باقي مجموعة الأخطاء متقسّمة على الخط ده.

## المكانين بنظرة سريعة [#المكانين-بنظرة-سريعة]

|                   | **أخطاء API**                                                 | **أخطاء الدفع**                                                                                            |
| ----------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| إمتى بتقابله      | بشكل متزامن، كرد على استدعاء API                              | بشكل غير متزامن، على الـ Payment Intent اللي فشل                                                           |
| فين بيعيش         | جسم رد الـ HTTP: `{ error: { type, code, ... }, request_id }` | حقل `lastPaymentError` بتاع الـ Payment Intent                                                             |
| إيه اللي سبّبه    | طلبك اترفض (تحقّق، أو مصادقة، أو مورد ناقص، أو تعارض)         | بطاقة العميل اترفضت، أو المعالج فشل                                                                        |
| مين جمهور الرسالة | المهندسين بتوعك                                               | عميلك (أحيانًا)، وفريق الدعم بتاعك (دايمًا)                                                                |
| مساحات الأكواد    | واحدة: `ApiErrorCode`                                         | ثلاثة: `PaymentErrorCode`، و`DeclineCode`، وكود الشبكة الخام                                               |
| شكل المعالِج      | `try / catch`، وتفرّع على `error.type` و`error.code`          | اقرا `lastPaymentError`، وتفرّع على `adviceCode`، واختار نص آمن للعميل                                     |
| المرجع            | [أكواد أخطاء API](/integrate/errors/api-error-codes)          | [أكواد أخطاء الدفع](/integrate/errors/payment-error-codes)، [أكواد الرفض](/integrate/errors/decline-codes) |

## حاجتين كل خطأ بيديهملك [#حاجتين-كل-خطأ-بيديهملك]

### `request_id` [#request_id]

كل رد API (سواء 2xx أو خطأ) بيتضمن `request_id` زي `req_3STkwmFGhGHoO0IX13BRo5iU`. في ردود الأخطاء بيبقى على المستوى الأعلى جنب `error`. اذكره في تذاكر الدعم، وسجّله جنب كل خطأ بيمسكه المعالِج بتاعك، واستخدمه علشان تلاقي الاستدعاء الفاشل في [Workbench ← السجلات](/integrate/workbench/logs-panel) حيث تقدر تشوف الطلب والرد كاملين.

عملية الدفع الفاشلة كمان ليها `request_id` على استدعاء الـ API الأساسي اللي طلّقها (الـ `POST /checkout/sessions/.../pay` من متصفح العميل). `lastPaymentError.chargeId` زائد وقت الفشل عادةً كفاية علشان تلاقي السجل ده لو احتجته.

### `docUrl` [#docurl]

كل كود خطأ ليه رابط مباشر لصفه على صفحة مرجع الأكواد في موقع التوثيق ده:

* أكواد أخطاء API ← `https://docs.xpay.app/integrate/errors/api-error-codes#<code>`
* أكواد أخطاء الدفع ← `https://docs.xpay.app/integrate/errors/payment-error-codes#<code>`
* أكواد الرفض ← `https://docs.xpay.app/integrate/errors/decline-codes#<code>`

لوحة التحكم بتعرض الرابط ده في تلميحات المعاملات وفي [Workbench ← السجلات](/integrate/workbench/logs-panel) علشان تقدر تضغط على طول من حدث فاشل لشرحه. في الواجهة التشغيلية بتاعتك إنت، اعرض الـ `docUrl` كرابط "اعرف أكتر" جنب رسالة الخطأ.

## اختار رايح فين بعد كده [#اختار-رايح-فين-بعد-كده]

<Cards>
  <Card icon="<TriangleAlert />" title="أخطاء API" href="/integrate/errors/api-errors">
    مغلّف الخطأ، وأنواع الأخطاء الثلاثة، ونمط المعالجة (try/catch + تفرّع على `type`).
  </Card>

  <Card icon="<Hash />" title="أكواد أخطاء API" href="/integrate/errors/api-error-codes">
    القائمة الكاملة لقيم `error.code` اللي ممكن تستقبلها على استدعاء API فاشل، متجمّعة حسب المجال.
  </Card>

  <Card icon="<CreditCard />" title="أخطاء الدفع" href="/integrate/errors/payment-errors">
    شكل `lastPaymentError`، والـ `adviceCode` اللي بيقرّر اللي تعمله بعد كده، وإزاي تقسّم النص بين
    عميلك وفريقك.
  </Card>

  <Card icon="<ListTree />" title="أكواد أخطاء الدفع" href="/integrate/errors/payment-error-codes">
    كل قيمة لـ `lastPaymentError.code`، مع النص الآمن للعميل والنص الموجّه للتاجر اللي XPay بيرجّعه.
  </Card>

  <Card icon="<Ban />" title="أكواد الرفض" href="/integrate/errors/decline-codes">
    سبب البنك المُصدِر للرفض، في `lastPaymentError.declineCode`. بالإضافة لكود الشبكة الخام اللي رجع
    من ماركة البطاقة.
  </Card>

  <Card icon="<Terminal />" title="لوحة السجلات" href="/integrate/workbench/logs-panel">
    دوّر على أي حالة فشل بـ `request_id` بتاعها وشوف الطلب والرد كاملين.
  </Card>
</Cards>