رموز الأخطاء

مرجع شامل لرموز أخطاء واجهة برمجة تطبيقات Mail.Land ومعانيها

تتضمن كل استجابة خطأ من واجهة برمجة تطبيقات MailLand حقل code يحتوي على رمز خطأ قابل للقراءة آليًا، وحقل message يحتوي على وصف مقروء للمستخدم.

صيغة استجابة الخطأ

Error response

{
  "code": "DOMAIN_NOT_VERIFIED",
  "message": "Domain is not verified",
  "timestamp": "2026-02-18T12:35:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

تتضمن بعض الأخطاء حقل details إضافي:

Error response with details

{
  "code": "IP_RATE_LIMIT_EXCEEDED",
  "message": "Too many requests from this IP. Retry after 45 seconds.",
  "details": {
    "limit": 300,
    "current": 301,
    "retryAfter": 45,
    "resetAt": "2026-02-18T12:35:00Z"
  }
}

التحقق من صحة الطلب (400)

يُعاد عندما يكون نص الطلب أو معلمات الاستعلام أو الرؤوس غير صالحة أو تفتقد حقولًا مطلوبة.

الرمز	الوصف
`INVALID_REQUEST`	طلب غير صالح بشكل عام
`VALIDATION_FAILED`	فشل التحقق من صحة حقل واحد أو أكثر
`INVALID_EMAIL_FORMAT`	صيغة عنوان البريد الإلكتروني غير صالحة
`WEBHOOK_DESTINATION_NOT_ALLOWED`	رفض عنوان الـ webhook بسبب سياسة الوجهة: يتم تسليم الـ webhooks عبر HTTPS على المنفذ 443 فقط، ولا يجوز أن تشير إلى خوادم MailLand أو عناوينها أو أسماء مضيفيها
`MISSING_CONTENT`	مهمل منذ 2026-04. استخدم `VALIDATION_FAILED`: نقاط النهاية send/scheduled تُرجع الآن أخطاء تحقق منظمة.
`CONTENT_TOO_LARGE`	"The message is too large to send: it would exceed the platform's message-size limit. Reduce the HTML, text, attachments or recipients.": الرسالة تتجاوز حد حجم الرسائل في المنصة. تُعيدها `POST /v1/transactional/send` و`send-batch` بالرمز `413`؛ ولا يوضع شيء في الطابور. قلّص الرسالة. وفي استيراد CSV يكون الرمز `400`
`transactional_recipient_limit_exceeded`	أكثر من 5 مستلمين على بيانات اعتماد معاملاتية (رمز بأحرف صغيرة)
`marketing_recipient_limit_exceeded`	أكثر من 1000 مستلم على بيانات اعتماد تسويقية (رمز بأحرف صغيرة)
`VALIDATION_FAILED`	إرسال مجمّع بأكثر من 10000 مستلم
`SEND_FAILED`	فشلت عملية إرسال البريد الإلكتروني، بما في ذلك "جميع المستلمين محظورون"
`BATCH_SEND_FAILED`	فشلت عملية الإرسال المجمّع
`IDEMPOTENCY_KEY_INVALID`	مفتاح التكرار الآمن فارغ أو غير صالح أو يتجاوز 255 محرفاً، أو أُرسل الرأس أكثر من مرة (فقط `send`/`send-batch`)
`IDEMPOTENCY_KEY_CONFLICT`	أُرسل رأس `X-Idempotency-Key` وحقل `idempotencyKey` معاً وقيمتاهما مختلفتان
`INVALID_CURSOR`	معامل ترقيم الصفحات بالمؤشر غير صالح
`PASSWORD_REQUIRED`	تأكيد كلمة المرور مطلوب
`RECIPIENT_SUPPRESSED`	المستلم مدرج في قائمة الحظر

المصادقة (401)

يُعاد عندما يفتقد الطلب بيانات الاعتماد أو تكون بيانات الاعتماد غير صالحة.

الرمز الوصف

UNAUTHORIZED X-API-Key مفقود أو غير صالح أو منتهي الصلاحية أو مُلغى: تُرجع البرمجية الوسيطة لمفتاح API هذا الرمز الوحيد في كل الحالات، مع message وصفية. لا تميّز بين الحالات المفقودة/غير الصالحة/المنتهية/الملغاة عبر الرمز. كلمة مرور تسجيل دخول خاطئة تُرجع أيضًا 401 UNAUTHORIZED.

LOGIN_REQUIRED تسجيل الدخول مطلوب لهذه العملية

الرمز	الوصف
`UNAUTHORIZED`	`X-API-Key` مفقود أو غير صالح أو منتهي الصلاحية أو مُلغى: تُرجع البرمجية الوسيطة لمفتاح API هذا الرمز الوحيد في كل الحالات، مع `message` وصفية. لا تميّز بين الحالات المفقودة/غير الصالحة/المنتهية/الملغاة عبر الرمز. كلمة مرور تسجيل دخول خاطئة تُرجع أيضًا `401 UNAUTHORIZED`.
`LOGIN_REQUIRED`	تسجيل الدخول مطلوب لهذه العملية

المصادقة الثنائية

تُرجع أخطاء المصادقة الثنائية 400 INVALID_REQUEST مع message وصفية (مثل "Invalid code"، "2FA is already enabled"). لا توجد رموز أخطاء مخصصة للمصادقة الثنائية، اقرأ حقل message.

التفويض (403)

يُعاد عندما لا يملك المستخدم المصادق عليه الصلاحية لتنفيذ الإجراء المطلوب.

الرمز	الوصف
`FORBIDDEN`	رفض الوصول بشكل عام
`INSUFFICIENT_PERMISSIONS`	المستخدم يفتقد الدور أو الصلاحية المطلوبة
`ACCOUNT_SUSPENDED`	تم تعليق حساب المستخدم
`ACCOUNT_DISABLED`	تم تعطيل حساب المستخدم
`ACCOUNT_NOT_ACTIVE`	حساب المستخدم غير نشط
`IP_NOT_ALLOWED`	عنوان IP الخاص بالعميل غير مدرج في قائمة السماح لبيانات الاعتماد
`VALIDATION_CREDENTIAL_REQUIRED`	تتطلب نقاط نهاية التحقق من البريد الإلكتروني مفتاح API لمنتج التحقق. يُرفض مفتاح الإرسال أو الاستقبال؛ وتُقبل جلسة مسجَّل الدخول أو مفتاح منتج التحقق
`PLAN_LIMIT_REACHED`	تم الوصول إلى حد الخطة، الترقية مطلوبة
`SENDING_BLOCKED`	مستوى توثيق الحساب لا يسمح بهذا الإرسال. ملاحظة: رفض `SendingBlocked` الخاص بمحرك السياسات نفسه هو `403`؛ ونفس الرمز القادم من مسار سياسة المعدل/الإحماء هو `429`، انظر قسم محرك السياسات أدناه.
`SUBSCRIPTION_EXPIRED`	انتهت صلاحية الاشتراك
`NO_ACTIVE_SUBSCRIPTION`	لا يوجد اشتراك نشط
`TENANT_APPROVAL_REQUIRED`	الحساب بانتظار المراجعة قبل أن يتمكن من الإرسال. إعادة المحاولة لا تفيد؛ تواصل مع الدعم
`MARKETING_NOT_YET_ALLOWED`	الإرسال التسويقي غير متاح بعد. يُفتح تلقائياً بعد سجل معاملات نظيف (500 رسالة معاملات مُسلَّمة على الأقل خلال 7 أيام على الأقل، وارتدادات صلبة دون 2% وشكاوى دون 0.1%)
`MARKETING_SUSPENDED`	البريد التسويقي غير متاح مؤقتاً على مستوى المنصة. البريد المعاملاتي غير متأثر؛ تُحفظ الحملات والأتمتة وتُستأنف عند تفعيل التسويق
`ACTION_REQUIRED`	يلزم إجراء من المستخدم قبل استئناف الإرسال. تُعاد أيضًا لكل إرسال أثناء نشاط تعليق إمكانية التسليم لمساحة العمل (تجاوز نسبة الارتداد/الشكاوى): يُعيد SMTP relay الكود `550` لنفس التعليق. راجع تعليقات إمكانية التسليم

غير موجود (404)

يُعاد عندما لا يكون المورد المطلوب موجودًا أو ينتمي إلى مساحة عمل مختلفة.

الرمز	الوصف
`RESOURCE_NOT_FOUND`	مورد عام غير موجود
`USER_NOT_FOUND`	المستخدم غير موجود
`WEBHOOK_NOT_FOUND`	الويب هوك غير موجود
`DELIVERY_NOT_FOUND`	تسليم الويب هوك غير موجود

تستخدم معظم استجابات 404 الرمز RESOURCE_NOT_FOUND. يوفر حقل message سياقًا حول المورد الذي لم يتم العثور عليه (مثل "Domain not found" أو "Template not found" أو "Campaign not found"). نقاط نهاية الويب هوك استثناء: إعادة محاولة تسليم ويب هوك تستخدم WEBHOOK_NOT_FOUND / DELIVERY_NOT_FOUND.

التعارض (409)

يُعاد عندما تتعارض العملية مع الحالة الحالية للمورد.

الرمز	الوصف
`CONFLICT`	تعارض عام في المورد
`IDEMPOTENCY_KEY_REUSED`	مفتاح التكرار الآمن مستخدم بالفعل لنقطة نهاية مختلفة في هذا الحساب (فقط `send`/`send-batch`)

النطاق والإرسال (422)

يُعاد عندما يكون الطلب سليمًا من حيث الصيغة لكن لا يمكن معالجته بسبب قيود منطق العمل.

الرمز	الوصف
`DOMAIN_NOT_FOUND`	النطاق غير موجود في مساحة العمل
`DOMAIN_NOT_VERIFIED`	النطاق لم يتم التحقق منه، أكمل إعداد DNS أولًا
`DOMAIN_NOT_ALLOWED_FOR_CREDENTIAL`	بيانات الاعتماد غير مصرّح لها لهذا النطاق المرسل
`CAMPAIGN_LINK_BLOCKED`	رابط في الحملة يشير إلى وجهة غير آمنة؛ لا تتم جدولة الحملة أو إرسالها
`DOMAIN_SUSPENDED`	تم تعليق النطاق
`DOMAIN_VERIFICATION_EXPIRED`	انتهت صلاحية التحقق من النطاق، أعد التحقق

الدفع مطلوب (402)

يُعاد عندما لا يغطي رصيد مساحة العمل العملية المطلوبة.

الرمز	الوصف
`INSUFFICIENT_CREDITS`	الرصيد غير كافٍ لإتمام العملية

تحديد المعدل (429)

يُعاد عندما يتجاوز الطلب حدود المعدل. يتضمن عادةً رأس Retry-After؛ إذا كان غائبًا، استخدم التراجع الأسي بدلاً من افتراض عدم وجود انتظار.

حدود معدل API

الرمز	الوصف
`RATE_LIMIT_EXCEEDED`	تم تجاوز حد معدل API العام
`IP_RATE_LIMIT_EXCEEDED`	تم تجاوز حد المعدل المستند إلى IP
`SUPPORT_RATE_LIMITED`	تم تجاوز حد معدل API الدعم الفني
`TOO_MANY_LOGIN_ATTEMPTS`	محاولات تسجيل دخول فاشلة كثيرة جداً، حظر مؤقت

حدود معدل إرسال البريد الإلكتروني

الرمز	الوصف
`DAILY_LIMIT_EXCEEDED`	تم تجاوز حد الإرسال اليومي
`WARMUP_LIMIT_EXCEEDED`	بلغ حساب الحد اليومي لمرحلة تهيئة الإرسال؛ يُعاد ضبطه عند 00:00 UTC (انظر تسخين عناوين IP)
`PAYMENT_DAILY_LIMIT_EXCEEDED`	تم بلوغ الحد اليومي لحساب متأخر السداد

سعة المنصة (429)

تعني حالات الرفض هذه أن المنصة، وليس حصة حسابك، هي التي تحدّ من الإرسال الجديد الآن. كل منها 429 مع ترويسة Retry-After، ولم يوضع شيء في الطابور، وإعادة المحاولة بالطلب نفسه آمنة. عبر SMTP تظهر كـ 421 Try again later: <message> مؤقتة. الحقل message هو النص الإنجليزي الذي تُعيده الواجهة.

الرمز	`message` (كما يُعاد)	متى تُعيد المحاولة
`WARMUP_POOL_BUDGET_EXCEEDED`	"Sending is temporarily paused for today. It resumes automatically at 00:00 UTC; no action is needed."	بعد `Retry-After` (الساعة 00:00 UTC التالية)
`WARMUP_POOL_BUDGET_EXCEEDED`	"Sending is briefly delayed. Please retry in a few minutes." (الرمز نفسه، عندما يتعذر التحقق من سعة المنصة لحظياً)	بعد `Retry-After` القصيرة
`WARMUP_POOL_EMPTY`	"Sending is temporarily paused. It resumes automatically; no action is needed."	بعد `Retry-After`؛ لا حاجة لأي إجراء
`PLATFORM_DAILY_CAPACITY_REACHED`	"Platform sending capacity for today is fully booked. This is a temporary platform-wide limit, not your account quota, and it resets at midnight UTC."	بعد `Retry-After` (الساعة 00:00 UTC التالية)
`PLATFORM_CAPACITY_PROTECTION`	"New sending is briefly paused to protect platform capacity. Mail already accepted is not affected. This is transient and clears on its own; retry shortly."	بعد `Retry-After` القصيرة
`PROBATION_CAP_REACHED`	"New accounts can send to N recipients per rolling 24 hours until our team has reviewed the account. Capacity returns as earlier sends age out of the 24-hour window; contact support to request a review." (أو «…cannot be verified right now, so sending is briefly paused…» عند انقطاع قصير)	بعد `Retry-After`، أو اطلب مراجعة من الدعم

الرسائل المقبولة سابقاً لا تتأثر أبداً. تعامل معها كأي 429 آخر: تراجع، والتزم بـ Retry-After، وأعد المحاولة. لا يوجد ما يلزم ضبطه أو ترقيته.

حدود التدفق

transactional_recipient_limit_exceeded وmarketing_recipient_limit_exceeded هما 400 وليس 429: انظر قسم التحقق من صحة الطلب أعلاه. BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL هو أيضاً 400: الإرسال المجمّع غير مسموح به على بيانات اعتماد معاملاتية بغض النظر عن حدود المعدل.

الحصص والفوترة

الرمز	الوصف
`QUOTA_EXCEEDED`	تم تجاوز حصة الاستخدام لفترة الفوترة الحالية

محرك السياسات

الرمز	الوصف
`SENDING_BLOCKED`	حظر محرك سياسة المعدل/الإحماء هذا الإرسال: مستوى التوثيق، أو قائمة السماح الخاصة بالصندوق التجريبي، أو تقييد الحساب، أو ارتفاع غير معتاد في الحجم
`MARKETING_PAUSED`	رسائل البريد التسويقي متوقفة مؤقتًا لمساحة العمل هذه

أخطاء الخادم (5xx)

الرمز	حالة HTTP	الوصف
`INTERNAL_ERROR`	500	خطأ غير متوقع في الخادم الداخلي
`AUTHENTICATION_FAILED`	500	فشل التحقق من مفتاح API داخليًا (وليس تسجيل دخول خاطئ، أعد المحاولة)
`TIMEOUT`	504	انتهت مهلة العملية
`SERVICE_UNAVAILABLE`	503	الخدمة غير متاحة مؤقتًا
`DATABASE_ERROR`	503	حدث خطأ في قاعدة البيانات

أخطاء الخادم (5xx) مؤقتة. أعد محاولة الطلب مع التراجع الأسي. إذا استمر الخطأ، تحقق من صفحة حالة MailLand أو تواصل مع الدعم الفني.

التعامل مع الأخطاء

استراتيجية إعادة المحاولة

حالة HTTP	إعادة المحاولة؟	الاستراتيجية
400	لا	أصلح الطلب وحاول مرة أخرى
401	لا	تحقق من بيانات الاعتماد أو جدّد الرمز المميز
403	لا	تحقق من الصلاحيات أو قم بترقية خطتك
404	لا	تحقق من معرّف المورد
409	لا	حل التعارض
422	لا	أصلح مشكلة منطق العمل (مثل التحقق من النطاق)
429	نعم	انتظر مدة `Retry-After`، ثم أعد المحاولة
500	نعم	أعد المحاولة مع التراجع الأسي (3 محاولات كحد أقصى)
503	نعم	أعد المحاولة مع التراجع الأسي (5 محاولات كحد أقصى)

قراءة رؤوس تحديد المعدل

تتضمن معظم الاستجابات X-RateLimit-Limit وX-RateLimit-Remaining:

الرأس	الوصف
`X-RateLimit-Limit`	الحد الأقصى للطلبات المسموح بها في النافذة الحالية
`X-RateLimit-Remaining`	الطلبات المتبقية في النافذة الحالية

يضيف 429 المستند إلى IP ما يلي:

الرأس	الوصف
`X-RateLimit-Reset`	الطابع الزمني بتوقيت UTC بصيغة ISO-8601 لإعادة تعيين النافذة الحالية (استجابات حد IP فقط)
`Retry-After`	عدد الثواني للانتظار قبل إعادة المحاولة

الخطوات التالية

حدود المعدل: مستويات حدود المعدل التفصيلية وأفضل الممارسات
المصادقة: إدارة الرموز المميزة ومفاتيح API
سجل التغييرات: تتبع تغييرات API

رموز الأخطاء

صيغة استجابة الخطأنسخ رابط القسم

التحقق من صحة الطلب (400)نسخ رابط القسم

المصادقة (401)نسخ رابط القسم

المصادقة الثنائيةنسخ رابط القسم

التفويض (403)نسخ رابط القسم

غير موجود (404)نسخ رابط القسم

التعارض (409)نسخ رابط القسم

النطاق والإرسال (422)نسخ رابط القسم

الدفع مطلوب (402)نسخ رابط القسم

تحديد المعدل (429)نسخ رابط القسم

حدود معدل APIنسخ رابط القسم

حدود معدل إرسال البريد الإلكترونينسخ رابط القسم

سعة المنصة (429)نسخ رابط القسم

حدود التدفقنسخ رابط القسم

الحصص والفوترةنسخ رابط القسم

محرك السياساتنسخ رابط القسم

أخطاء الخادم (5xx)نسخ رابط القسم

التعامل مع الأخطاءنسخ رابط القسم

استراتيجية إعادة المحاولةنسخ رابط القسم

قراءة رؤوس تحديد المعدلنسخ رابط القسم

الخطوات التاليةنسخ رابط القسم

في هذه الصفحة