الأخطاء ورموز الحالة

كيف تُبلغ واجهة برمجة تطبيقات Mersal عن الأخطاء، وأشكال الاستجابة القياسية المتوقعة.

3 دقيقة قراءة

تتبع واجهة برمجة تطبيقات Mersal اتفاقيات REST القياسية: 2xx للنجاح، و4xx لأخطاء العميل (شيء في طلبك يحتاج إلى تصحيح)، و5xx لأخطاء الخادم (حدث خطأ ما من جهة Mersal — يمكن إعادة المحاولة بأمان بعد فترة).

استجابات الأخطاء الشائعة

403 — أخطاء المصادقة والاشتراك

تُرجعها نقاط إرسال القنوات (sms/send، whatsapp/send، email/send، ونظيراتها GET /api/get/{channel}/{id?}) عندما يكون مفتاح API مفقودًا أو غير صالح، أو عندما تكون صلاحية اشتراك الحساب منتهية.

الحالة	المحتوى
مفتاح API مفقود	`{"status":"error","message":"API key is required. Provide via header (Api-key) or URL parameter (api_key)","error":"Invalid Api Key"}`
مفتاح API غير صالح	`{"status":"error","error":"Invalid Api Key"}`
انتهاء صلاحية الاشتراك	`{"status":"error","error":"Your Subscription Is Expired! Buy A New Plan"}`

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

422 — فشل التحقق من صحة البيانات

تُرجع عندما يفشل نص الطلب في التحقق من الصحة — مثلاً مصفوفة contact مفقودة، أو مصفوفة contact فارغة، أو حقل number/email/message/subject مفقود، أو قيمة schedule_at غير صحيحة الصيغة. يتبع هذا شكل أخطاء التحقق القياسي في Laravel لكل حقل: errors كائن تُستخدم فيه مسارات الحقول كمفاتيح، وكل قيمة هي مصفوفة من الرسائل القابلة للقراءة الخاصة بذلك الحقل.

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

تستخدم مفاتيح الحقول تدوين النقطة مع فهرس المصفوفة، فمثلاً contact.0.number يشير إلى حقل number الخاص بالعنصر الأول في مصفوفة contact. عند إرسال عدة جهات اتصال، تحقق من كل مفتاح مفهرَس في errors بدلاً من افتراض أن عنصرًا واحدًا فقط قد فشل.

الاتفاقيات العامة

2xx — نجح الطلب. عادةً ما تُرجع عمليات الإرسال success: true (أو status: "success") مع محتوى data يصف ما تم إدراجه في قائمة الانتظار أو جدولته.
4xx — هناك شيء في الطلب يحتاج إلى تصحيح من جانبك: مصادقة غير صحيحة أو مفقودة (403)، أو بيانات طلب غير صالحة (422).
5xx — خطأ غير متوقع من جهة الخادم. هذه الحالات نادرة؛ إذا واجهت واحدة، فمن الآمن إعادة المحاولة بعد فترة قصيرة.

لا تفترض أن HTTP 200 يعني التسليم

استجابة 2xx الناجحة تعني أن Mersal قبلت رسالتك وأدرجتها في قائمة الانتظار — وليس أنها وصلت إلى المستلم بعد. استخدم Webhooks أو نقاط الاستعلام GET /api/get/{channel}/{id?} للتأكد من حالة التسليم النهائية.

راجع أيضًا

المصادقة — كيفية تجنب أخطاء 403.
حدود المعدل — سلوك التقييد في بوابة الذكاء الاصطناعي وبوابات القنوات.

Webhooks

حدود المعدل

هل ساعدتك هذه الصفحة؟