کدهای خطا

هر پاسخ خطا از API 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)

هنگامی بازگردانده می‌شود که بدنه درخواست، پارامترهای query یا هدرها نامعتبر یا فاقد فیلدهای الزامی باشند.

کد	توضیحات
`INVALID_REQUEST`	درخواست نامعتبر عمومی
`VALIDATION_FAILED`	یک یا چند فیلد در اعتبارسنجی رد شدند
`INVALID_EMAIL_FORMAT`	فرمت آدرس ایمیل نامعتبر است
`WEBHOOK_DESTINATION_NOT_ALLOWED`	نشانی وب‌هوک توسط سیاست مقصد رد شد: وب‌هوک‌ها فقط روی HTTPS و درگاه ۴۴۳ تحویل داده می‌شوند و نباید به سرورها، نشانی‌ها یا نام‌های میزبان خود MailLand اشاره کنند
`MISSING_CONTENT`	از ۲۰۲۶-۰۴ منسوخ شده. به‌جای آن از `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`	بیش از ۵ گیرنده روی یک اعتبارنامهٔ تراکنشی (کد با حروف کوچک)
`marketing_recipient_limit_exceeded`	بیش از ۱۰۰۰ گیرنده روی یک اعتبارنامهٔ بازاریابی (کد با حروف کوچک)
`VALIDATION_FAILED`	ارسال دسته‌ای با بیش از ۱۰٬۰۰۰ گیرنده
`SEND_FAILED`	عملیات ارسال ایمیل ناموفق بود، از جمله «تمام گیرندگان سرکوب شده‌اند»
`BATCH_SEND_FAILED`	عملیات ارسال دسته‌ای ناموفق بود
`IDEMPOTENCY_KEY_INVALID`	کلید تکرارناپذیری خالی، نامعتبر یا بیش از ۲۵۵ نویسه است، یا هدر بیش از یک‌بار ارسال شده است (فقط `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`	ارسال بازاریابی هنوز باز نیست. پس از داشتن سابقهٔ تراکنشی تمیز (دست‌کم ۵۰۰ ایمیل تراکنشی تحویل‌شده در دست‌کم ۷ روز، با بانس سخت زیر ۲٪ و شکایت زیر ۰٫۱٪) خودکار باز می‌شود
`MARKETING_SUSPENDED`	ارسال بازاریابی به‌طور موقت در کل پلتفرم در دسترس نیست. ایمیل تراکنشی تحت‌تأثیر نیست؛ کمپین‌ها و اتوماسیون‌ها نگه‌داری می‌شوند و با فعال‌شدن بازاریابی ادامه می‌یابند
`ACTION_REQUIRED`	اقدام کاربر پیش از ازسرگیری ارسال الزامی است. همچنین تا زمانی که فضای کاری یک توقف تحویل‌پذیری فعال داشته باشد (نقض نرخ برگشتی/شکایت)، برای هر ارسالی بازگردانده می‌شود؛ SMTP relay برای همین توقف کد `550` برمی‌گرداند. به توقف‌های تحویل‌پذیری مراجعه کنید

یافت نشد (404)

هنگامی بازگردانده می‌شود که منبع درخواستی وجود نداشته باشد یا متعلق به فضای کاری دیگری باشد.

کد	توضیحات
`RESOURCE_NOT_FOUND`	منبع عمومی یافت نشد
`USER_NOT_FOUND`	کاربر وجود ندارد
`WEBHOOK_NOT_FOUND`	وب‌هوک وجود ندارد
`DELIVERY_NOT_FOUND`	تحویل وب‌هوک وجود ندارد

بیشتر پاسخ‌های ۴۰۴ از کد 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`	سقف روزانهٔ دورهٔ راه‌اندازی ارسال حساب شما پر شده است؛ در ۰۰:۰۰ UTC بازنشانی می‌شود (ببینید گرم‌کردن IP)
`PAYMENT_DAILY_LIMIT_EXCEEDED`	محدودیت روزانه برای حساب دارای پرداخت معوق اعمال شده است

ظرفیت پلتفرم (429)

این ردها یعنی اکنون خودِ پلتفرم، و نه سهمیهٔ حساب شما، ارسال‌های جدید را محدود می‌کند. هرکدام 429 با هدر Retry-After است، چیزی در صف قرار نگرفته و ارسال مجدد همان درخواست امن است. در SMTP همین ردها به‌صورت 421 Try again later: <message> (موقت) برمی‌گردند. message همان متن انگلیسیِ برگردانده‌شده توسط API است.

کد	`message` (همان‌طور که برمی‌گردد)	زمان تلاش مجدد
`WARMUP_POOL_BUDGET_EXCEEDED`	"Sending is temporarily paused for today. It resumes automatically at 00:00 UTC; no action is needed."	پس از `Retry-After` (۰۰:۰۰ 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` (۰۰:۰۰ 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 key
تاریخچه تغییرات: پیگیری تغییرات API

کدهای خطا

فرمت پاسخ خطاکپی پیوند بخش

اعتبارسنجی درخواست (400)کپی پیوند بخش

احراز هویت (401)کپی پیوند بخش

احراز هویت دو مرحله‌ایکپی پیوند بخش

مجوزدهی (403)کپی پیوند بخش

یافت نشد (404)کپی پیوند بخش

تداخل (409)کپی پیوند بخش

دامنه و ارسال (422)کپی پیوند بخش

پرداخت الزامی (402)کپی پیوند بخش

محدودیت نرخ (429)کپی پیوند بخش

محدودیت‌های نرخ APIکپی پیوند بخش

محدودیت‌های نرخ ارسال ایمیلکپی پیوند بخش

ظرفیت پلتفرم (429)کپی پیوند بخش

محدودیت‌های جریانکپی پیوند بخش

سهمیه و صورتحسابکپی پیوند بخش

موتور سیاست‌گذاریکپی پیوند بخش

خطاهای سرور (5xx)کپی پیوند بخش

مدیریت خطاهاکپی پیوند بخش

استراتژی تلاش مجددکپی پیوند بخش

خواندن هدرهای محدودیت نرخکپی پیوند بخش

مراحل بعدیکپی پیوند بخش

در این صفحه