Developers

كتالوج الأخطاء

يحمل كل خطأ رمزًا ثابتًا قابلًا للقراءة آليًا وحالة HTTP متسقة. الرمز هو ما يجب أن يعتمد عليه تكاملك: النص قد يتطور، الرمز لن يتغير.

شكل الخطأ

الشكل الحالي بسيط عمدًا. إنه مستقر، وهذا هو المهم: رمز، ولا شيء يكشف تفاصيل داخلية.

الشكل الحالي — استجابة حقيقيةjson

{ "error": "rate_stale" }

مع سبب قابل للقراءة البشرية — استجابة حقيقيةjson

{
  "error": "rail_not_open",
  "reason": {
    "fr": "La retenue TDS de 1 % et l’enregistrement FIU-IND exigent une entite locale…",
    "en": "The 1% TDS withholding and FIU-IND registration require a local entity…"
  }
}

تحمل بعض الأخطاء كائن سبب ثنائي اللغة، يُقصد عرضه كما هو للمستخدم. القناة المغلقة (closed rail) هي أحدها: السبب يشرح قيدًا تنظيميًا محددًا، وليس انقطاعًا، وعرضه يوفر طلب دعم. ستضيف واجهة API ذات الإصدارات معرف طلب إلى هذا الغلاف، حتى تتمكن من توجيهنا إلى سطر محدد في سجلاتنا.

الرموز السارية

يتم إرجاع هذه الرموز اليوم بواسطة نقطة نهاية عرض السعر (quote endpoint).

الرموز السارية
code	HTTP	ماذا يعني	ماذا تفعل
`invalid_request`	400	يفشل جسم الطلب في التحقق من المخطط: حقل مفقود، أو نوع خاطئ، أو قيمة خارج الحدود المسموح بها.	تحقق من أن المبلغ سلسلة وليس رقمًا، وأن الاتجاه هو بالضبط "sell" أو "receive".
`invalid_amount`	400	لا يمكن تحليل المبلغ، أو يحمل كسورًا عشرية أكثر مما يقبله الأصل أو العملة.	اقتطع إلى دقة الوحدة: 6 منازل عشرية لـ USDT، و8 لـ BTC، و2 لليورو، و0 للفرنك الأفريقي.
`unknown_asset_or_rail`	404	معرّف الأصل أو القناة غير موجود في الكتالوج.	المعرّفات مستقرة ولا يتم إعادة تعيينها أبدًا. أعد تحميل الكتالوج بدلاً من تخمينها.
`rail_not_open`	409	القناة موجودة ولكنها غير مفتوحة. تحمل الاستجابة السبب الدقيق، باللغتين.	اعرض السبب كما هو: فهو يفسر قيدًا تنظيميًا، وليس انقطاعًا. اعرض قناة مفتوحة في نفس البلد.
`asset_not_offered`	409	الأصل موجود في الكتالوج ولكن غير معروض — حالة الأصول ذات إخفاء الهوية المعزز.	لا تعرضه في منتقي الخاص بك. يعيده الكتالوج مع سببه حتى تتمكن من شرحه.
`rate_stale`	503	آخر سعر معروف يتجاوز الحد الأقصى للعمر المسموح به. يرفض المحرك الاقتباس بدلاً من تقديم سعر قديم كسعر ثابت.	أعد المحاولة بعد بضع ثوانٍ. لا تخزن آخر اقتباس ناجح لملء الفجوة: سيكون ذلك بالضبط الخطأ الذي يمنعه هذا الكود.
`rate_unavailable`	503	لا يتوفر سعر لهذا الزوج أصل / عملة.	عطّل الزوج في واجهتك بدلاً من إظهار تقدير. التقدير المعروض يصبح توقعًا.
`quote_failed`	500	خطأ غير متوقع أثناء الحساب. لا يتم إرجاع أي اقتباس.	أعد المحاولة مرة واحدة؛ إذا استمر الخطأ، فاكتب إلينا بالطابع الزمني الدقيق للاستدعاء.

الرموز من العقد المنشور

ترافق هذه الرموز نقاط النهاية غير المفتوحة بعد. تم نشرها بحيث تتم كتابة معالجة الأخطاء الخاصة بك مرة واحدة.

الرموز السارية
code	HTTP	ماذا يعني	ماذا تفعل
`unauthorized`	401	المفتاح مفقود أو ملغى أو مستخدم في بيئة خاطئة.	مفتاح sk_test_ لا يعمل في بيئة الإنتاج، والعكس صحيح أيضًا: هذا مقصود.
`idempotency_conflict`	409	تم استخدام نفس مفتاح idempotency بالفعل مع نص طلب مختلف.	المفتاح ينتمي إلى نية واحدة. إذا تغير المحتوى، يتغير المفتاح؛ وإلا فلا يمكن تحديد أي من الطلبين يجب إعادة تشغيله.
`quote_expired`	409	لقد تجاوز الاقتباس نافذة القفل الخاصة به.	أعد الاقتباس واجعل المبلغ الجديد مقبولاً. نحن لا نعيد التسعير بصمت ضد العميل أبدًا.
`beneficiary_rejected`	422	تفشل تفاصيل المستفيد في التحقق من قناة الدفع: مجموع اختباري غير صالح، أو تنسيق غير مطابق، أو اسم لا يطابق الهوية الموثقة.	يحدد الرد الحقل المخالف. يجب أن يكون اسم المستفيد هو الهوية الموثقة: لا يمكن الدفع لطرف ثالث.
`country_not_served`	451	البلد الوجهة غير مخدوم: عقوبات، أو إجراءات تقييدية، أو غياب إطار محلي.	تم اختيار رمز 451 عمدًا بدلاً من 404: عندما نرفض، نقول إنه رفض ولماذا.
`rate_limited`	429	عدد كبير جدًا من المكالمات خلال النافذة المنزلقة.	احترم ترويسة Retry-After. الاقتباسات رخيصة في قائمة الانتظار، ومكلفة عند تكرار الضرب.
`not_found`	404	المورد غير موجود، أو لا ينتمي إلى مفتاحك.	كلتا الحالتين ترجعان نفس الرمز: الرد الذي يميز بينهما سيسمح لأي شخص بتعداد مراجع الآخرين.

ما ليس خطأ

المبلغ خارج حدود القناة يُرجع عرض سعر صالحًا، مع كائن limitError. إنه ليس فشلًا: إنها معلومات يجب أن تعرضها واجهتك.

مقتطف من الاستجابةjson

"limitError": { "code": "below_min", "limit": "20.00" }

معاملة هذه الحالة كخطأ HTTP ستحرمك من المبلغ المحسوب، وبالتالي من القدرة على إخبار المستخدم "أنت مقصر بمبلغ 16.53 يورو عن الحد الأدنى لطريقة الدفع هذه". ينطبق الحد على المبلغ الصافي، الذي يستلمه المستفيد.

إعادة المحاولة، أم لا

ثلاث عائلات، ثلاثة سلوكيات. إعادة محاولة خطأ تحقق في حلقة تملأ سجلاتك فقط.

لا تعيد المحاولة أبدًا

invalid_request، invalid_amount، unknown_asset_or_rail، asset_not_offered، unauthorized. الخطأ في الطلب: إعادة محاولته دون تغيير تعطي نفس النتيجة. أصلحه، أو اعرض السبب.

أعد المحاولة مع تراجع (backoff)

rate_stale، rate_unavailable، quote_failed، وأي تحديد للمعدل. انتظر بضع ثوانٍ، مع فجوة متزايدة بين المحاولات. لا تملأ الفجوة بعرض سعر مخزن مؤقتًا.

اطلب قرارًا

rail_not_open، quote_expired، beneficiary_rejected، country_not_served. الموقف يحتاج إلى اختيار بشري: اعرض قناة أخرى، أو عرض سعر جديد، أو تفاصيل مصححة.