الأخطاء

رموز حالة HTTP ورموز الأخطاء التي تعيدها واجهة تيرا باي، وكيف تتعامل مع كل منها.

تستخدم تيرا باي رموز حالة HTTP القياسية: 2xx تعني النجاح، و4xx تعني مشكلة في الطلب يمكنك إصلاحها، و5xx تعني خللًا من جهتنا أو من شبكة الدفع.

لكل خطأ الشكل نفسه بصيغة JSON:

{
  "error": {
    "code": "validation_error",
    "message": "Some fields are missing or invalid.",
    "details": {
      "fields": {
        "amount": "Expected integer, received float",
        "currency": "Invalid enum value. Expected 'KWD' | 'BHD' | 'OMR' | 'JOD' | 'SAR' | 'AED' | 'QAR' | 'EGP', received 'USD'"
      }
    }
  }
}

الحقل	الوصف
`code`	رمز ثابت يمكن للبرامج قراءته. اعتمد عليه في منطقك.
`message`	شرح مقروء لسجلاتك. قد يتغير، فلا تحلّله برمجيًا.
`details`	بيانات إضافية اختيارية. في `validation_error` يربط `details.fields` كل حقل غير صالح برسالة. وتُكتب الحقول المتداخلة بمسار منقّط مثل `customer.email` أو `metadata.order_id`.

رموز الأخطاء

HTTP	`code`	المعنى	ما الذي تفعله
401	`unauthorized`	مفتاح API مفقود أو غير صحيح أو ملغى أو غير معروف.	تحقّق من الترويسة `Authorization: Bearer sk_…` ومن وضع المفتاح.
403	`forbidden`	المفتاح صالح لكنه غير مسموح له بهذا الإجراء.	تأكد أنك تستخدم المفتاح والحساب الصحيحين.
403	`merchant_not_active`	طلب حي قبل اعتماد الحساب وتفعيله، أو الحساب موقوف.	استخدم مفتاح اختبار، أو أكمل التسجيل.
404	`payment_not_found`	عملية الدفع غير موجودة، أو تخص الوضع الآخر (اختبار/حي).	تحقّق من المعرّف ومن وضع المفتاح.
404	`refund_not_found`	الاسترداد غير موجود، أو يخص الوضع الآخر.	تحقّق من المعرّف ومن وضع المفتاح.
404	`payment_link_not_found`	رابط الدفع غير موجود، أو يخص الوضع الآخر.	تحقّق من المعرّف ومن وضع المفتاح.
404	`not_found`	أي كائن أو مسار آخر غير موجود، مثل نقطة نهاية Webhook.	تحقّق من المعرّف والمسار ووضع المفتاح.
409	`conflict`	طلب آخر بالمفتاح `Idempotency-Key` نفسه لا يزال قيد المعالجة.	انتظر قليلًا وأعِد المحاولة بالمفتاح نفسه.
409	`idempotency_conflict`	استُخدم مفتاح `Idempotency-Key` هذا من قبل مع طلب مختلف.	استخدم مفتاحًا جديدًا للطلب الجديد. راجع منع التكرار.
422	`validation_error`	معامل أو أكثر مفقود أو غير صالح، بما في ذلك رابط لا يبدأ بـ `https://` في الوضع الحي، أو `payment_method` لا يدعمها حسابك (`"unsupported"`)، أو مبلغ بعملة ذات ثلاث منازل لا ينتهي بصفر في بعض الحسابات.	راجع `details.fields` وصحّح الطلب. راجع وسائل الدفع وحسابك.
422	`refund_exceeds_amount`	مبلغ الاسترداد أكبر من المتبقي القابل للاسترداد. تحمل `details.remaining` المبلغ المتبقي.	استرد بحد أقصى `amount − amount_refunded`.
422	`payment_not_refundable`	عملية الدفع ليست `succeeded`، فلا يمكن استردادها.	استرد المدفوعات الناجحة فقط.
429	`rate_limited`	طلبات كثيرة بهذا المفتاح (1,200 طلب في الدقيقة). تحدد `details.retry_after_seconds` والترويسة `Retry-After` موعد إعادة المحاولة.	انتظر، ثم أعِد المحاولة بالمفتاح `Idempotency-Key` نفسه. راجع حدود معدل الطلبات.
500	`internal_error`	خطأ غير متوقع من جهتنا.	أعِد المحاولة بالمفتاح `Idempotency-Key` نفسه، وتواصل مع الدعم إن استمر.
502	`gateway_error`	أعادت شبكة الدفع خطأ أو لم تستجب.	أعِد المحاولة بالمفتاح `Idempotency-Key` نفسه بعد قليل.

قد تُضاف رموز أخطاء جديدة. تعامل مع أي رمز غير معروف وفق رمز حالة HTTP الخاص به.

التعامل مع الأخطاء

const res = await fetch('https://api.teyra.co/v1/payments', options);
const body = await res.json();

if (!res.ok) {
  const { code, message, details } = body.error;
  if (code === 'validation_error') console.warn('Invalid fields', details?.fields);
  else if (res.status === 429 || res.status >= 500) await retryLater(); // keep the same Idempotency-Key
  throw new Error(`Teyra Pay ${res.status} ${code}: ${message}`);
}

رفض البطاقة لا ينتج عنه خطأ HTTP. إنشاء عملية الدفع ينجح (201)، ثم تنتقل العملية لاحقًا إلى status: "failed" مع قيمتي failure_code وfailure_message. تعرف ذلك من GET /v1/payments/:id أو من إشعار payment.failed.

الأخطاء

رموز الأخطاء

التعامل مع الأخطاء

فشل الدفع ليس خطأً في الـ API

في هذه الصفحة