الأخطاء الشائعة

تتناول هذه الصفحة أكثر الأخطاء شيوعًا التي قد تواجهها أثناء التكامل مع واجهة برمجة التطبيقات (API) الخاصة بمرسال، مع توضيح معنى كل خطأ، وأسبابه المحتملة، وكيفية معالجته. وللاطلاع على المرجع الكامل لأكواد الحالة (Status Codes) وتنسيق الاستجابات (Response Format)، يُرجى مراجعة الأخطاء وأكواد الحالة.

403 — "Invalid Api Key"

{
  "status": "error",
  "error": "Invalid Api Key"
}

ده معناه إن الهيدر Api-key (أو البديل api_key كـ query/body parameter) ناقص، أو مكتوب غلط، أو مش مطابق لمفتاح حقيقى في حسابك.

إزاي تحلها:

• اتأكد إن اسم الهيدر بالظبط Api-key — مش Authorization، ولا apikey، ولا X-Api-Key. نقاط نهاية إرسال القنوات (/api/sms/send، /api/whatsapp/send، /api/email/send) مش بتستخدم مصادقة Bearer token؛ الأسلوب ده محجوز لـ AI Gateway بس.
• تأكد إنك نسخت المفتاح من صفحة API key في حسابك بلوحة التحكم، من غير مسافات زيادة أو قص للمفتاح.
• لو عملت regenerate للـ API key بتاعك مؤخراً، تأكد إن كل تكامل بيستخدم المفتاح القديم اتحدّث — شوف إدارة مفاتيح API.

شوف المصادقة لتفاصيل نظام المصادقة الكامل.

403 — "Your Subscription Is Expired! Buy A New Plan"

{
  "status": "error",
  "error": "Your Subscription Is Expired! Buy A New Plan"
}

ده خطأ مختلف عن مفتاح غير صالح — مفتاح الـ API بتاعك صحيح، لكن باقة/اشتراك حسابك انتهت. نقاط نهاية إرسال القنوات بتتطلب اشتراك نشط بغض النظر عن صحة المفتاح، فكل طلب إرسال هيرجع الخطأ ده لحد ما تجدّد الباقة.

422 — "Validation failed"

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "contact": ["The contact field is required."],
    "contact.0.number": ["The contact.0.number field is required."]
  }
}

ده شكل خطأ التحقق القياسى فى Laravel: message بيقولك إن التحقق فشل عموماً، وerrors هو object مفاتيحه أسماء الحقول، وكل قيمة فيه array بمشاكل محددة في الحقل ده.

إزاي تقراها:

• توضّح المفاتيح بالضبط أي حقل قد فشل التحقق منه؛ فالمفتاح contact يعني أن الـ array بأكمله مفقود، بينما يعني contact.0.number (أو contact.*.number في حال وجود أكثر من عنصر) أن أحد المستلمين داخل الـ array ينقصه رقمه أو عنوانه.
• ابدأ بتصحيح الحقول المذكورة في errors أولًا، فهي القائمة الرسمية لمشكلات الطلب، وليست مجرد خطأ عام.

أسباب شائعة:

• إرسال array فاضي أو ناقص لـ contact — كل نقطة إرسال محتاجة مستلم واحد على الأقل.
• عنصر مستلم ناقصه الحقل اللي القناة محتاجاه (number للـ SMS/واتساب، عنوان إيميل للإيميل).
• JSON مش مظبوط، أو هيدر Content-Type غلط، وده بيخلّي الحقول توصل فاضية حتى لو بعتّها فعلاً.

أسلوب عام لتشخيص الأخطاء

1. اقرأ كود حالة HTTP الأول — 403 معناها مشكلة مصادقة/فوترة، 422 معناها مشكلة في شكل الطلب، وأى كود في نطاق 5xx بيشير لمشكلة من جانب المنصة يستاهل إنك تبلّغ عنها.
2. اقرأ حقل error أو message في جسم الـ JSON — استجابات الأخطاء في مرسال معمولة عشان تتقرأ مباشرة، مش بس تُستخدم كعلامة نجاح/فشل.
3. لـ 422 بالتحديد، راجع object الـ errors حقل حقل بدل ما تخمّن الناقص.
4. لو الطلب شكله صحيح ولسه بيفشل، شوف مشاكل تسليم الرسائل — بعض الأعطال بتحصل بعد ما التحقق ينجح، على مستوى البوابة أو المزوّد.