الأخطاء | توثيق جسر ألفابت

كل خطأ من /api/v1 له الشكل نفسه: كائن error فيه رمز code تقرؤه البرامج ورسالة message يقرؤها البشر. بعض الرموز تضيف حقولاً مذكورة أدناه. اعتمد في منطقك على code لا على message، فالرسالة قد تتغير.

json

{
  "error": {
    "code": "validation_failed",
    "message": "The amount field must be at least 250. (and 1 more error)",
    "fields": {
      "amount": ["The amount field must be at least 250."],
      "order_reference": ["The order reference field is required."]
    }
  }
}

كل رموز الأخطاء

HTTP	`code`	ما الذي حدث	ما العمل
401	`unauthenticated`	لا توجد ترويسة `Authorization: Bearer …`.	أرسل مفتاح API. راجع المصادقة.
401	`invalid_api_key`	المفتاح غير معروف أو أُلغي أو تم تبديله.	استخدم المفتاح الحالي من لوحة التحكم.
403	`application_disabled`	التطبيق متوقف.	تواصل مع ألفابت. إعادة المحاولة لن تفيد.
403	`application_pending_review`	لم تفعّل ألفابت التطبيق بعد.	انتظر التفعيل.
403	`application_suspended`	علّقت ألفابت التطبيق.	تواصل مع ألفابت. إعادة المحاولة لن تفيد.
403	`ip_not_allowed`	جاء الطلب من عنوان IP خارج القائمة المسموحة لتطبيقك.	أرسل الطلب من خادم مسموح، أو اطلب من ألفابت إضافة العنوان.
404	`not_found`	لا توجد دفعة بهذا المعرّف لهذا التطبيق في هذا الوضع، أو المسار غير معروف.	تحقق من المعرّف، ومن أنك تستخدم مفتاحاً من الوضع نفسه (تجريبي أو فعلي).
409	`order_reference_already_paid`	لمرجع الطلب `order_reference` دفعة `pending` أو `paid` أو مستردة. يضيف `payment_id`.	استخدم تلك الدفعة: حوّل العميل إلى `checkout_url` الخاص بها، أو اعتبر الطلب مدفوعاً.
409	`idempotency_key_reused`	استُخدم `Idempotency-Key` سابقاً مع جسم مختلف.	استخدم مفتاحاً جديداً للطلب المختلف.
409	`idempotency_request_in_progress`	الطلب الأول بهذا `Idempotency-Key` ما زال قيد التنفيذ.	أعد المحاولة بعد لحظات.
409	`payment_not_cancellable`	طُلب إلغاء دفعة لم تعد `pending`. يضيف `status`.	إن كانت `paid` فسلّم الطلب أو استرده؛ الدفعة المدفوعة لا تُلغى.
409	`payment_not_refundable`	طُلب استرداد دفعة ليست `paid` أو `partially_refunded`. يضيف `status`.	اجلب الدفعة لترى حالتها.
409	`payment_busy`	الدفعة قيد التحديث في تلك اللحظة.	أعد المحاولة بعد بضع ثوانٍ.
422	`validation_failed`	حقل أو أكثر غير صالح. يضيف `fields`: كل حقل مع رسائله.	صحّح الحقول المذكورة. الجسم نفسه يعطي الرد نفسه.
422	`method_required`	تطبيقك يقدّم أكثر من طريقة دفع ولم يُرسل `method`.	أرسل `method`.
422	`method_not_enabled`	طريقة الدفع `method` غير مفعّلة لتطبيقك، أو لا توجد طريقة مفعّلة.	تواصل مع ألفابت.
422	`amount_below_minimum`	قيمة `amount` أقل من الحد الأدنى لتطبيقك. يضيف `min_amount`.	ارفع المبلغ.
422	`amount_above_maximum`	قيمة `amount` أعلى من الحد الأقصى لتطبيقك. يضيف `max_amount`.	قسّم الطلب أو اطلب من ألفابت مراجعة الحد.
422	`return_url_not_allowed`	أُرسل `return_url` بمضيف مختلف عن مضيف عنوان العودة المسجَّل لتطبيقك.	لا ترسل `return_url` أو أرسل عنواناً على المضيف نفسه. راجع الدفعات.
422	`refund_amount_exceeds_refundable`	مبلغ الاسترداد أكبر من المتبقي. يضيف `refundable_amount`.	استرد `refundable_amount` على الأكثر.
422	`refunds_processed_manually`	طُلب استرداد بمفتاح فعلي. يضيف `docs_url`.	اطلب الاسترداد من لوحة التحكم. راجع الاسترداد.
429	`rate_limited`	أكثر من 120 طلباً في الدقيقة بهذا المفتاح.	انتظر عدد الثواني في ترويسة `Retry-After` ثم أعد المحاولة.
502	`provider_error`	رفض مزوّد الدفع الطلب أو لم يرد. عند الإنشاء يضيف `payment_id`، وتصبح تلك الدفعة `failed`.	أعد المحاولة لاحقاً. عند الإنشاء أنشئ دفعة جديدة، فالمرجع نفسه صار متاحاً.
500	`server_error`	حدث خلل من جهة الجسر.	أعد المحاولة مع تباعد زمني. عند الإنشاء أعدها بـ `Idempotency-Key` نفسه.
غير ذلك	`http_error`	أي خطأ HTTP آخر، مثل `405` لطريقة غير صحيحة على مسار.	تحقق من الطريقة والمسار.

إعادة المحاولة بأمان

أخطاء 4xx، ما عدا 409 idempotency_request_in_progress و409 payment_busy و429، ستعطي الرد نفسه حتى تغيّر الطلب.
أخطاء 5xx وأعطال الشبكة يمكن إعادة محاولتها. أرسل Idempotency-Key مع POST /api/v1/payments كي لا تنشئ إعادة المحاولة دفعة ثانية أبداً. راجع الدفعات.