رموز الأخطاء

تُعيد كل أخطاء الواجهة البرمجية البنية نفسها:

{
  "error": {
    "code": "payment_rejected",
    "message": "The selected currency is invalid.",
    "documentation_url": "https://app.so-amtar.com/docs/errors#payment_rejected"
  }
}

رمز HTTP	المعنى
400	طلب غير صالح البنية (ترويسة غير صالحة، JSON غير صالح)
401	المصادقة (مفتاح مفقود أو غير صالح أو ملغى)
403	التفويض (صلاحية غير كافية)
404	المورد غير موجود لدى هذا التاجر
409	تعارض (عدم اتساق في التكرار الآمن، طلب قيد التنفيذ)
422	تحقق الأعمال (تجاوز الحد، حالة غير متسقة)
429	تجاوز حد الطلبات
500	خطأ داخلي (أبلغ الدعم)
502	Orange Money غير متاح

القائمة الكاملة

المصادقة

• missing_credentials — ترويسة Authorization مفقودة
• invalid_api_key — مفتاح غير معروف أو ملغى أو منتهي الصلاحية، أو عنوان IP خارج القائمة المسموح بها
• scope_insufficient — المفتاح لا يملك الصلاحية التي يتطلبها هذا المسار

التكرار الآمن (Idempotency)

• idempotency_key_too_long — أكثر من 255 حرفًا
• idempotency_conflict — المفتاح نفسه مع جسم مختلف، أو الطلب ما زال قيد التنفيذ

المدفوعات

• payment_rejected — تحقق الأعمال (المزوّد، العملة، دقة المبلغ، الحد، KYC)
• gateway_error — رفض Orange Money بدء الدفع (502)
• transaction_not_found — معرّف أو مرجع غير معروف لدى هذا التاجر (أو أُنشئ في الوضع الآخر)

الاسترداد (POST/v1/refunds، الصلاحية can_refund)

• transaction_not_found (404) — معاملة غير معروفة لهذا التاجر
• refunds_disabled (422) — الاسترداد غير مفعّل لحسابك
• refund_environment_mismatch (422) — مفتاح اختبار على معاملة live أو العكس
• transaction_not_refundable (422) — حالة المعاملة ليست success
• non_payment_transaction_refund (422) — لا يُسترد إلا الدفع (وليس الدفعات الصادرة)
• provider_refund_unsupported (422) — مزوّد الخدمة لا يدعم الاسترداد
• refund_payer_phone_missing (422) — لا يحمل الدفع رقم الدافع لإعادة المبلغ إليه
• amount_must_be_positive (422) — يجب أن يكون amount أكبر من صفر
• transaction_already_fully_refunded (422) — استُرد الدفع بالكامل مسبقًا
• refund_exceeds_refundable (422) — amount يتجاوز المبلغ المتبقي القابل للاسترداد
• refund_rejected (422) — رُفض الاسترداد لسبب تجاري آخر
• scope_insufficient (403) — المفتاح لا يملك الصلاحية can_refund
• refund_not_found (404) — GET/v1/refunds/{id}: معرّف أو مرجع غير معروف

الدفعات الصادرة (payouts)

• payout_not_allowed_in_test_mode — تتطلب الدفعات الصادرة مفتاح live (sk_live_…)

تقسيم المدفوعات (splits)

• split_rejected — المجموع يتجاوز مبلغ المعاملة، أو المستفيد غير نشط، أو المعاملة منتهية

ما العمل

الرمز	الإجراء الموصى به
4xx (تحقق)	صحّح الطلب واستخدم Idempotency-Key جديدًا
401	تحقق من المفتاح. لا تُعِد المحاولة.
409	راجع منطق التكرار الآمن لديك
429	انتظر مدة Retry-After ثم أعد المحاولة
5xx	أعد المحاولة بنفس Idempotency-Key مع انتظار أُسّي
502	Orange Money غير متاح: أعد المحاولة بعد بضع ثوانٍ

الإبلاغ عن خطأ

راسل support@so-amtar.com مع ذكر:

• رمز الخطأ
• قيمة documentation_url
• الطابع الزمني الدقيق (UTC)
• قيمة merchant_ref أو id الخاص بـ SOAMTAR
• ترويسة X-Request-Id في الاستجابة (إن وُجدت)