الأخطاء - Wave API

تُعيد الأخطاء غلافًا ثنائيّ اللغة متّسقًا يحتوي على كود قابل للقراءة آليًّا، ورسالتين بالإنجليزيّة والعربيّة، وrequest id للدعم، ورابط توثيق:

{
  "error_code": "VALIDATION_ERROR",
  "message": "to must be a valid KSA phone number",
  "message_ar": "خطأ في التحقق من البيانات",
  "request_id": "req_abc123",
  "docs_url": "https://wave.sa/docs/errors"
}

اعتمِد دائمًا في التفريع على error_code (الثابت)، لا على نصّ الرسالة.

حالات HTTP

الحالة	المعنى
`400`	خطأ في التحقّق — راجع جسم الطلب.
`401`	API key مفقود أو غير صالح.
`403`	استُنفدت دقائق الـ sandbox للمشروع، أو يفتقر الـ key إلى الإذن المطلوب.
`429`	تجاوُز حدّ المعدّل — راجع حدود المعدّل.
`5xx`	خطأ في الـ upstream/الشبكة الهاتفيّة — آمن لإعادة المحاولة مع backoff.

أكواد الأخطاء

`error_code`	الحالة النموذجيّة	المعنى
`VALIDATION_ERROR`	400	فشل جسم الطلب في التحقّق.
`INVALID_PHONE_NUMBER`	400	الـ `to` ليس رقمًا سعوديًّا صالحًا.
`INVALID_API_KEY`	401	key مفقود أو مُشوَّه أو غير معروف.
`INSUFFICIENT_PERMISSIONS`	403	يفتقر الـ key إلى إذن `web_callback`.
`SANDBOX_MINUTES_EXCEEDED`	403	استنفد المشروع دقائق الـ sandbox الـ 15. تُرفض المكالمة الحقيقيّة في الـ sandbox، وتبقى المكالمات المحاكاة تعمل. راجع وضع الـ Sandbox.
`RATE_LIMIT_EXCEEDED`	429	أكثر من 60 طلبًا في الدقيقة — راجع حدود المعدّل.
`CALL_FAILED`	502	تعذّر على الـ telephony backend إجراء المكالمة.

القائمة الكاملة للأكواد (بما في ذلك أكواد OTP والـ webhook والـ session وNafath) موجودة في مخطّط Error بمرجع الـ API.

Request id

تحمل كلّ استجابة معرّف الطلب في ترويسة الاستجابة x-request-id. وتحمله استجابة الخطأ أيضًا في الجسم باسم request_id (بالقيمة نفسها). ويستطيع عميل المتصفّح قراءة الترويسة (فهي مكشوفة عبر CORS). استخدم المعرّف للعثور على الطلب في سجلّ الطلبات في البوابة، وأرفِقه عند التواصل مع الدعم — فهو يتيح لنا العثور على الطلب المحدّد في السجلّات.