الانتقال إلى المحتوى الرئيسي
تُعيد الأخطاء غلافًا ثنائيّ اللغة متّسقًا يحتوي على كود قابل للقراءة آليًّا، ورسالتين بالإنجليزيّة والعربيّة، و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خطأ في التحقّق — راجع جسم الطلب.
401API key مفقود أو غير صالح.
403انتهت تجربة الـ sandbox، أو يفتقر الـ key إلى الإذن المطلوب.
429تجاوُز حدّ المعدّل — راجع حدود المعدّل.
5xxخطأ في الـ upstream/الشبكة الهاتفيّة — آمن لإعادة المحاولة مع backoff.

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

error_codeالحالة النموذجيّةالمعنى
VALIDATION_ERROR400فشل جسم الطلب في التحقّق.
INVALID_PHONE_NUMBER400الـ to ليس رقمًا سعوديًّا صالحًا.
INVALID_API_KEY401key مفقود أو مُشوَّه أو غير معروف.
INSUFFICIENT_PERMISSIONS403يفتقر الـ key إلى إذن web_callback.
SANDBOX_EXPIRED403انقضت تجربة الـ sandbox البالغة 30 دقيقة.
SANDBOX_DESTINATION_NOT_ALLOWED403لا يمكن لمكالمات الـ sandbox أن ترِنّ إلّا على رقم تسجيل المالك.
RATE_LIMIT_EXCEEDED429أكثر من 60 طلبًا في الدقيقة — راجع حدود المعدّل.
CALL_FAILED502تعذّر على الـ telephony backend إجراء المكالمة.
القائمة الكاملة للأكواد (بما في ذلك أكواد OTP والـ webhook والـ session وNafath) موجودة في مخطّط Error بمرجع الـ API.

​
Request id

تحمل كلّ استجابة request_id. أرفِقه عند التواصل مع الدعم — فهو يتيح لنا العثور على الطلب المحدّد في السجلّات.