تخطَّ إلى المحتوى

حدود المعدل

تمنع حدود المعدل عميلا واحدا مزدحما من إبطاء الواجهة البرمجية على الجميع، وتحدّ من الضرر الذي قد يسببه مفتاح مسرّب. تُحتسب الطلبات في نوافذ ثابتة مدة كل منها 60 ثانية.

الحد طلبات كل 60 ثانية يُحتسب لكل
لكل مفتاح API معدل باقتك: 60 في Free، و300 في Starter، و1200 في Pro، و3000 في Business مفتاح API
لكل مستخدم مسجل الدخول 300 المستخدم
لكل عنوان IP 600، أو معدل باقتك لكل مفتاح إن كان أعلى عنوان IP للعميل
لكل مؤسسة 1200، أو معدل باقتك لكل مفتاح إن كان أعلى كل مفاتيح المؤسسة ومستخدميها معا
العمليات المجمعة 20 مفتاح API أو مستخدم، فوق الحدود السابقة

يجب أن يجتاز الطلب كل هذه الحدود. ينطبق حد العمليات المجمعة على نقاط النهاية المكلفة:

  • POST /v1/contact-imports وPOST /v1/contact-imports/:id/start
  • GET /v1/contacts/export.csv
  • POST /v1/campaigns/:id/estimate وPOST /v1/campaigns/:id/start

لا يخضع GET /health لحدود المعدل.

سرعة الإرسال حد مستقل عن معدل الطلبات: يلتزم كل هاتف بفترة انتظار بين الرسائل لحماية شرائحك، وللحملات ratePerMinute خاص بها. انظر إرسال الرسائل.

تحمل كل استجابة حالة الحد الخاص ببيانات اعتمادك:

RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
الترويسة المعنى
RateLimit-Limit الطلبات المسموحة في النافذة.
RateLimit-Remaining الطلبات المتبقية في هذه النافذة.
RateLimit-Reset الثواني المتبقية حتى تبدأ نافذة جديدة.
Retry-After في رد 429 من حد بيانات الاعتماد: عدد الثواني التي تنتظرها.

ترد الواجهة البرمجية بالحالة 429 Too Many Requests مع code: "rate_limited":

{
"type": "https://docs.smsfabric.com/errors/rate_limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Rate limit exceeded. Retry in 18s.",
"code": "rate_limited",
"requestId": "req_v8y1b4e7h0k3n6q9t2w5z8c1"
}

انتظر Retry-After ثانية (أو RateLimit-Reset إذا لم توجد Retry-After) ثم أعد المحاولة. إذا لم توجد أي من الترويستين، تراجع بفواصل متزايدة تبدأ من ثانية. الرد 429 لا يرسل شيئا، فإعادة المحاولة آمنة، ومع ذلك احتفظ بالمفتاح Idempotency-Key نفسه.

نافذة طرفيّة
# -i shows the RateLimit-* headers
curl -i https://api.smsfabric.com/v1/messages?limit=1 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

حدود المعدل وحصص الباقة

Section titled “حدود المعدل وحصص الباقة”

قد يعود الإرسال بردين مختلفين بالحالة 429. اعتمد على code للتمييز بينهما:

429 rate_limited 429 quota_exceeded
ما الذي نفد الطلبات في نافذة الستين ثانية الحالية. رسائل الباقة لليوم أو للشهر (حدود الباقة).
كم يدوم ثوان: انظر Retry-After. حتى 00:00 بتوقيت UTC، أو حتى أول الشهر التالي: انظر params.resetsAt.
ما العمل انتظر وأعد المحاولة بالمفتاح Idempotency-Key نفسه. أوقف الإرسال، واحتفظ بالرسائل في طابورك وأرسلها بعد resetsAt. إعادة المحاولة قبل ذلك تعيد الرد نفسه.
حزمة Node تعيد المحاولة عنك. ترمي الخطأ فورا، ولا تعيد المحاولة أبدا.

لا يرسل أي منهما شيئا. لتعرف كم بقي من الحصة قبل إرسال كبير، اقرأ usage.messagesToday وusage.messagesThisMonth من GET /v1/org/plan (الباقات).

لخدمة التحقق حدود خاصة لكل رقم ولكل دولة ولكل مؤسسة، ترد بالرمز 429 verify_resend_limited أو 429 verify_velocity_exceeded مع Retry-After بالثواني. مدة الانتظار هنا دقائق: اعرضها للمستخدم بدل إعادة المحاولة في حلقة. انظر التحقق من أرقام الهواتف.

  • استخدم webhooks بدل الاستعلام المتكرر عن حالة الرسائل.
  • اجمع حتى 100 مستلم في كل إرسال (recipientsPerRequest في باقتك).
  • استخدم limit=200 عند تصفح القوائم، وlistAll() في حزمة SDK.
  • وزّع المهام المجدولة على الدقيقة بدل إطلاقها كلها عند الثانية صفر.

كل الحدود مذكورة في الحدود.