YASend API

الأخطاء

لكل خطأ الشكل نفسه، مع رمز code ثابت قابل للمعالجة آلياً:

{
  "error": {
    "code": "SESSION_NOT_CONNECTED",
    "message": "Session is not connected",
    "status": 409,
    "requestId": "req_3f1c9a7e2b4d4c0e8a1b2c3d"
  }
}
  • اعتمد على code لا على message. الرسائل موجّهة للبشر وقد تتغير.
  • حقول إضافية: تضيف بعض الأخطاء سياقاً، مثل retryAfter (بالثواني) وlimit وused وmessageId، أو details لأخطاء التحقق من المدخلات.
  • الدعم: اذكر requestId عند التواصل مع الدعم.

رموز الحالة

HTTP المعنى
400 مدخلات خاطئة (رقم هاتف خاطئ، محتوى ناقص…)
401 مفتاح API مفقود أو غير صالح
402 باقتك لا تسمح بذلك حالياً: منتهية، أو بلغت حداً، أو الميزة غير مشمولة
403 غير مسموح بهذا المفتاح (مثل مفتاح جلسة لإجراء على مستوى الحساب)
404 غير موجود، أو ليس لك: معرّفات الحسابات الأخرى تظهر دائماً كـ 404
409 تعارض مع الحالة الحالية (جلسة غير متصلة، موقوفة…)
422 فشل التحقق: المحتوى لا يطابق المخطط
429 طلبات كثيرة أو بلغت حصة. انتظر Retry-After ثانية
5xx مشكلة من جهتنا أو تعذّر الوصول لواتساب. أعد المحاولة بتباعد متزايد (مع Idempotency-Key للإرسال)

الرموز

المصادقة والمفاتيح

الرمز HTTP
INVALID_API_KEY 401 مفتاح مفقود أو خاطئ أو ملغى
KEY_SCOPE 403 مفتاح جلسة استُخدم لإجراء على مستوى الحساب
TENANT_SUSPENDED 403 الحساب موقوف. تواصل مع الدعم
MISSING_SESSION_ID 400 عدة جلسات ولا يوجد sessionId
SESSION_NOT_FOUND 404 لا توجد جلسة كهذه في حسابك

الإرسال

الرمز HTTP
VALIDATION_ERROR 422 المحتوى غير صالح. راجع details[].field
INVALID_MESSAGE 400 لا نص ولا وسائط
INVALID_JID 400 to ليس رقماً أو معرّفاً صالحاً
SESSION_NOT_CONNECTED 409 الجلسة غير متصلة أو لم تُربط بعد
SESSION_PAUSED 409 الإرسال موقوف لهذه الجلسة
RATE_LIMITED 429 تباعد محرك الأمان (لكل رقم أو لكل مستلم)
WARMUP_RESTRICTED 429 حد إحماء الرقم الجديد أو متطلباته. راجع الأمان
CONTENT_BLOCKED 429 رسالة هي رابط فقط، أو فيها كلمة محظورة، أو نص مكرر
SESSION_AT_RISK 429 توقف الإرسال لحماية رقم يواجه مشكلة
WORKER_TIMEOUT 504 لم يجب واتساب في الوقت المحدد، وقد تكون الرسالة أُرسلت أو لا
SESSION_UNAVAILABLE / CAPACITY_EXHAUSTED 503 مؤقت. أعد المحاولة بعد قليل
IDEMPOTENCY_KEY_REUSED 422 استُخدم هذا Idempotency-Key مع محتوى مختلف
IDEMPOTENCY_IN_PROGRESS 409 الطلب الأول بهذا المفتاح ما زال جارياً
INVALID_IDEMPOTENCY_KEY 400 من 1 إلى 255 محرف ASCII قابل للطباعة
MESSAGE_NOT_FOUND 404 معرّف رسالة غير معروف
MESSAGE_NOT_CANCELABLE 409 قيد الإرسال أو انتهت

نتائج الإرسال غير المتزامن (message.failed وerror.code)

تفشل الرسالة غير المتزامنة بأحد رموز الإرسال أعلاه، أو بأحد هذين:

الرمز
EXPIRED لم تُرسل قبل expiresAt
DELIVERY_UNKNOWN ربما أُرسلت. لا تُعاد محاولتها كي لا تتكرر أبداً

الجلسات

الرمز HTTP
QR_PENDING 202 رمز QR قيد الإنشاء. أعد المحاولة بعد لحظات
QR_NOT_AVAILABLE 404 شغّل الجلسة أولاً
ALREADY_AUTHENTICATED 409 مرتبطة بالفعل
INVALID_PHONE 400 رقم هاتف رمز الاقتران غير صالح
PAIRING_NOT_READY 504 أعد طلب رمز الاقتران

الباقة والفوترة

الرمز HTTP
SUBSCRIPTION_REQUIRED 402 لا توجد باقة فعالة
SUBSCRIPTION_EXPIRED 402 انتهت التجربة أو الباقة: الجلسات منقطعة (ومرتبطة) والإرسال متوقف خلال فترة السماح
SUBSCRIPTION_SUSPENDED 402 انتهت فترة السماح: الجلسات موقوفة حتى التجديد
TRIAL_NOT_AVAILABLE 402 هذا الرقم أو الحساب استخدم الفترة التجريبية من قبل
PLAN_LIMIT_SESSIONS / PLAN_LIMIT_WEBHOOKS / PLAN_LIMIT_API_KEYS 402 بلغت العدد المسموح في باقتك، ويبيّنه limit
PLAN_FEATURE_UNAVAILABLE 402 تحتاج باقة أعلى (مثل تجميع الأرقام)
DAILY_LIMIT_REACHED / MEDIA_LIMIT_REACHED 429 حصة اليوم، وتتجدد عند 00:00 بتوقيت UTC
PERIOD_LIMIT_REACHED 429 حصة الرسائل في فترة باقتك
API_RATE_LIMITED 429 عدد طلبات API في الدقيقة المسموح في باقتك

الويب هوك

الرمز HTTP
INVALID_WEBHOOK_URL 400 ليس رابط http(s) عاماً
INVALID_EVENT 400 نوع حدث غير معروف
WEBHOOK_NOT_FOUND / DELIVERY_NOT_FOUND 404
WEBHOOK_DISABLED 409 فعّل الويب هوك قبل إعادة الإرسال
PAYLOAD_NOT_KEPT 409 لم يُحفظ محتوى رسالة هذا التسليم (لا نخزّنه أبداً) فلا يمكن إعادة إرساله