401 authentication_required
مفتاح Bearer مفقود أو غير صالح.
استخدم مفتاح الاختبار أو المفتاح السري الحي الصحيح في ترويسة Authorization.
تصحيح أسرع
حوّل كل خطأ في الـ API إلى خطوة تالية.
معظم مشكلات التكامل تندرج ضمن المصادقة أو التحقق أو الويب هوك أو دعم المسار أو سلوك الاستقصاء. يربط هذا الدليل العرض بالإصلاح التالي.
400 validation_error
حقل مطلوب مفقود أو غير صالح.
تحقّق من المبلغ والعملة والشبكة ورابط الويب هوك وعنوان المحفظة وصيغة JSON.404 not_found
لم يتم العثور على جلسة الدفع أو نقطة النهاية.
تأكّد من معرّف الجلسة ومسار التوجيه. للحالة العامة استخدم /payments/{id}/status.409 fee_delegation_unavailable
إعدادات تفويض الرسوم أو المسار أو دعم الشبكة غير مفعّلة.
استخدم الدفع القياسي عبر المحفظة أو فعّل سياسة التاجر والمسار المدعوم أولًا.فشل تسليم 422 webhook
لم تُرجع نقطة نهاية التاجر حالة 2xx.
تحقّق من HTTPS وتحليل الجسم الخام والتحقق من التوقيع والمهلة وقواعد الجدار الناري.429 rate_limited
عدد كبير جدًا من طلبات API الموثّقة.
تراجع وأعد المحاولة لاحقًا وتجنّب الاستقصاء المفرط.ما زلت متعثّرًا؟
أرسل معرّف الطلب ونقطة النهاية ومعرّف الجلسة ورمز الاستجابة والحمولة بعد تنقيتها. لا ترسل أبدًا المفاتيح الخاصة أو أسرار الويب هوك.
تواصل مع الدعم افتح وثائق API فحص أخطاء JSON-RPC في بيئة تجربة MCP تشخيص أخطاء توقيعات الويب هوك 422
حزم NPM SDK الرسمية (v0.2.0) وخادم MCP عن بُعد
تكامل أسرع باستخدام حزم XPayr الرسمية وخادم MCP دون تثبيت
ثبّت @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0)أو @xpayr/mcp-server (v1.0.0) من NPM، أو نفّذ استدعاءات أدوات JSON-RPC 2.0 المباشرة عبر POST https://xpayr.com/api/mcp.