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

# خطأ في التعامل

> ظرف استجابة GOWA، ورموز الأخطاء وحالات HTTP ، وكيفية التعامل معها.

## ظرف الاستجابة

كل استجابة من JSON لها نفس الشكل:

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": { }
}
```

| الحقل | الوصف |
| - | - |
| `code` | `SUCCESS` أو رمز الخطأ. استخدم هذا، جنبا إلى جنب مع حالة HTTP، إلى الفرع. |
| `message` | تفاصيل مقروءة من البشر: يمكن أن تتغير الصياغة بين إطلاق النار؛ لا تحللها. |
| `results` | الحمولة على النجاح. عادة ما يتم حذفها من الأخطاء. |

## رموز الخطأ

| الكود | HTTP | المعنى | ماذا نفعل |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | حقل مفقود أو غير صالح. يحدد `message` اسمه. | إصلاح الطلب. |
| `INVALID_JID` | 400 | الرقم غير موجود على WhatsApp، أو أن وحدة التنفيذ المشترك مشوهة. | تحقق من الرقم؛ لا إعادة المحاولة. |
| `ALREADY_LOGGED_IN` | 400 | طلب تسجيل الدخول لجهاز تم تسجيل الدخول مسبقاً. | لا شيء، أو تسجيل الخروج أولاً. |
| `DEVICE_ID_REQUIRED` | 400 | لم يتم إعطاء أي جهاز والخادم يحتوي على صفر أو عدة أجهزة. | إرسال `X-Device-Id`. |
| `AUTHENTICATION_ERROR` | 401 | الجهاز غير مسجل الدخول إلى WhatsApp (أو فشل مصادقة WhatsApp). | تحقق من `/devices/{id}/status`؛ زوج مرة أخرى إذا لزم الأمر. |
| `NOT_FOUND` | 404 | لم يتم العثور على المصدر (رسالة، الدردشة، الجدول…). | تحقق من المعرف |
| `DEVICE_NOT_FOUND` | 404 | `X-Device-Id` اسم جهاز غير معروف. | تحقق من معرف الفتحة أو JID. |
| `AVATAR_HIDDEN` | 403 | يتم إخفاء الصورة الشخصية من خلال إعدادات الخصوصية. | لا تتعامل مع هذا على أنه غياب مؤكد، أو تمحو صورة مخبأة فقط على هذه النتيجة. |
| `AVATAR_NOT_SET` | 404 | ليس لدى جهة الاتصال أي صورة شخصية. | مسح صورة مؤقتة فقط بعد التحقق من هذه التعليمة البرمجية، وليس أي 404. |
| `CROSS_SITE_REQUEST_BLOCKED` | 403 | مصدر المتصفح غير موثوق. | قم بخدمة لوحة التحكم عبر HTTP(S) وتكوين المصدر الموثوق به بالضبط. |
| `CONTEXT_ERROR` | 408 | وقد ألغيت العملية أو انتهت مدتها داخليا. | أعد المحاولة مرة واحدة. |
| `WA_REACHOUT_TIMELOCK` | 429 | WhatsApp حجب محادثات جديدة من هذا الحساب مؤقتا. | إيقاف التوعية؛ انظر [إرسال حدود](https://gowa-docs.mintlify.site/ar/advanced/rate-limiting.md). |
| `INTERNAL_SERVER_ERROR` | 500 | فشل غير متوقع، بما في ذلك الذعر المسترد. | إعادة المحاولة مع التراجع؛ تحقق من السجلات. |
| `QR_CHANNEL_ERROR` | 500 | تعذر الحصول على رمز QR. | إعادة محاولة تسجيل الدخول. |
| `SESSION_SAVED_ERROR` | 500 | لا يمكن أن تستمر الدورة. | تحقق من التخزين والأذونات. |
| `UPLOAD_MEDIA_ERROR` | 500 | فشل تحميل الوسائط إلى WhatsApp. | إعادة المحاولة؛ تحقق من الحجم والصيغة. |
| `WEBHOOK_ERROR` | 500 | إعدادات Webhook أو خطأ في التوصيل. | تحقق من رابط webhook. |
| `INVALID_WA_CLI` | 500 | لم يتم تهيئة عميل WhatsApp للجهاز. | إعادة الاتصال أو تسجيل الدخول مرة أخرى. |
| `DEVICE_MANAGER_UNAVAILABLE` | 503 | لم يتم تهيئة مدير الجهاز. | إعادة المحاولة لفترة قصيرة؛ تحقق من سجلات بدء التشغيل. |
| `GATEWAY_TIMEOUT` | 504 | تجاوز الطلب 45 ثانية. | قد يكون الإجراء قد اكتمل؛ تحقق قبل إعادة المحاولة. |

تُعيد حالات فشل المصادقة الأساسية الرمز `401` من طبقة المصادقة قبل الوصول إلى معالجات GOWA؛ لذا اعتبر أي `401` لا يتضمن حقل `code` من GOWA دلالةً على بيانات اعتماد غير صحيحة.

## إعادة المحاولة بأمان

الإرسال هو **ليس محتوى**: GOWA ليس لديه مفتاح idempowerness. إذا كان وقت الإرسال خارج (`504`، خطأ في الشبكة)، قد يتم تسليم الرسالة بالفعل. قبل إعادة الإرسال، تحقق من المحادثة مع `GET /chat/{chat_jid}/messages?is_from_me=true&limit=5`، أو قبول خطر التكرار.

| إعادة المحاولة | لا تقم بإعادة المحاولة |
| - | - |
| `500 INTERNAL_SERVER_ERROR`، `UPLOAD_MEDIA_ERROR`، `CONTEXT_ERROR`، `503` | أخطاء `400`، `INVALID_JID`، `404`، `401`، `WA_REACHOUT_TIMELOCK` |

استخدم الظهر الأسي مع حد أقصى، والحد من المحاولات.

```javascript theme={null}
async function gowa(path, body, attempt = 1) {
  const res = await fetch(`http://localhost:3000${path}`, {
    method: "POST",
    headers: {
      Authorization: "Basic " + Buffer.from("admin:changeme").toString("base64"),
      "Content-Type": "application/json",
      "X-Device-Id": "my-device",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (res.ok) return data.results;

  const retryable = [500, 503].includes(res.status) && data.code !== "INVALID_JID";
  if (retryable && attempt < 4) {
    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
    return gowa(path, body, attempt + 1);
  }
  throw Object.assign(new Error(data.message || res.statusText), { code: data.code, status: res.status });
}
```

## تصحيح الأخطاء

* تشغيل مع `APP_DEBUG=true` للحصول على سجلات مفصلة.
* تحقق من الجهاز: `GET /devices/{device_id}/status` (`is_connected`, `is_logged_in`).
* يؤكد `GET /health` فقط العملية وقاعدة البيانات قد تم استحداثها؛ ولا يتحقق من اتصال WhatsApp.


## Related topics

- [التعامل مع الوسائط](https://gowa-docs.mintlify.site/ar/examples/media-handling.md)
- [تكامل Chatwoot](https://gowa-docs.mintlify.site/ar/integrations/chatwoot.md)
- [قائمة التحديثات المباشرة للاشتراكات في الجهاز](https://gowa-docs.mintlify.site/ar/api-reference/newsletter/قائمة-التحديثات-المباشرة-للاشتراكات-في-الجهاز.md)
- [الاشتراك في التحديثات المباشرة للنشرة الإخبارية](https://gowa-docs.mintlify.site/ar/api-reference/newsletter/الاشتراك-في-التحديثات-المباشرة-للنشرة-الإخبارية.md)
- [تصدير المشاركين في المجموعة كـ CSV](https://gowa-docs.mintlify.site/ar/api-reference/group/تصدير-المشاركين-في-المجموعة-كـ-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.