> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wave.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# الأخطاء

> غلاف الخطأ ثنائيّ اللغة في Wave، وأكواد الأخطاء، وحالات HTTP.

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

```json theme={null}
{
  "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_EXPIRED`                 | 403               | انقضت تجربة الـ sandbox البالغة 30 دقيقة.                        |
| `SANDBOX_DESTINATION_NOT_ALLOWED` | 403               | لا يمكن لمكالمات الـ sandbox أن ترِنّ إلّا على رقم تسجيل المالك. |
| `RATE_LIMIT_EXCEEDED`             | 429               | أكثر من 60 طلبًا في الدقيقة — راجع حدود المعدّل.                 |
| `CALL_FAILED`                     | 502               | تعذّر على الـ telephony backend إجراء المكالمة.                  |

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

## Request id

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