Rate Limit و Retry

در نسخه اولیه سرویس عمومی، Rate Limit پیش‌فرض ۱۲۰ درخواست در دقیقه برای هر API Key است. این مقدار یک حد عملیاتی پایه است و ممکن است در آینده براساس Plan یا نوع Endpoint متفاوت شود.

پاسخ محدودیت

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Correlation-Id: 4ac56ce65f3f44fca4370761283a583c

نمونه Body:

{
  "code": "rate_limited",
  "message": "تعداد درخواست‌ها از حد مجاز عبور کرده است.",
  "correlationId": "4ac56ce65f3f44fca4370761283a583c"
}

Client باید Retry-After را رعایت کند و از Retry سریع و هم‌زمان خودداری کند.

سیاست Retry پیشنهادی

برای 429 و خطاهای موقت 502/503 از Exponential Backoff همراه با Jitter استفاده کنید. نمونه فاصله‌های پایه می‌تواند ۱، ۲، ۴ و ۸ ثانیه باشد، اما اگر Retry-After وجود داشت اولویت با همان Header است.

در POST /v1/messages، Retry فقط باید با همان Idempotency-Key درخواست اولیه انجام شود تا Timeout سمت Client باعث ثبت پیام تکراری نشود.

برای 400، 401 و 403 Retry خودکار معمولاً مناسب نیست و ابتدا باید Request، Credential یا Permission اصلاح شود.

جلوگیری از Burst

اگر تعداد زیادی پیام دارید، درخواست‌ها را با Queue سمت Backend خود کنترل کنید و به‌جای Burst لحظه‌ای، نرخ ارسال را هموار نگه دارید. Rate Limit تعداد درخواست API است و لزوماً با ظرفیت ارسال اپراتور یا تعداد پیامک در ثانیه یکسان نیست.