حدود المعدل
تمنع حدود المعدل عميلا واحدا مزدحما من إبطاء الواجهة البرمجية على الجميع، وتحدّ من الضرر الذي قد يسببه مفتاح مسرّب. تُحتسب الطلبات في نوافذ ثابتة مدة كل منها 60 ثانية.
الحدود
Section titled “الحدود”| الحد | طلبات كل 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/startGET /v1/contacts/export.csvPOST /v1/campaigns/:id/estimateوPOST /v1/campaigns/:id/start
لا يخضع GET /health لحدود المعدل.
سرعة الإرسال حد مستقل عن معدل الطلبات: يلتزم كل هاتف بفترة انتظار بين الرسائل لحماية شرائحك، وللحملات ratePerMinute خاص بها. انظر إرسال الرسائل.
الترويسات
Section titled “الترويسات”تحمل كل استجابة حالة الحد الخاص ببيانات اعتمادك:
RateLimit-Limit: 300RateLimit-Remaining: 287RateLimit-Reset: 41| الترويسة | المعنى |
|---|---|
RateLimit-Limit |
الطلبات المسموحة في النافذة. |
RateLimit-Remaining |
الطلبات المتبقية في هذه النافذة. |
RateLimit-Reset |
الثواني المتبقية حتى تبدأ نافذة جديدة. |
Retry-After |
في رد 429 من حد بيانات الاعتماد: عدد الثواني التي تنتظرها. |
عند بلوغ الحد
Section titled “عند بلوغ الحد”ترد الواجهة البرمجية بالحالة 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-* headerscurl -i https://api.smsfabric.com/v1/messages?limit=1 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"import { SMSFabric } from '@smsfabric/sdk';
// The SDK retries 429 responses on its own, waiting Retry-After (or RateLimit-Reset).// maxRetries sets how many times (default 2).const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY, maxRetries: 4 });
for await (const message of sf.messages.listAll({ status: 'failed' })) { console.log(message.id, message.errorCode);}import osimport timeimport requests
def get(url: str, **params) -> dict: headers = {"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]} for attempt in range(5): res = requests.get(url, headers=headers, params=params, timeout=30) if res.status_code != 429: res.raise_for_status() return res.json() wait = res.headers.get("Retry-After") or res.headers.get("RateLimit-Reset") or 2 ** attempt time.sleep(int(wait)) raise RuntimeError("still rate limited")
print(get("https://api.smsfabric.com/v1/messages", limit=1))<?phpfunction getWithBackoff(string $url): array { for ($attempt = 0; $attempt < 5; $attempt++) { $headers = []; $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY')], CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) { $parts = explode(':', $line, 2); if (count($parts) === 2) { $headers[strtolower(trim($parts[0]))] = trim($parts[1]); } return strlen($line); }, ]); $body = curl_exec($ch); if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 429) { return json_decode($body, true); } sleep((int) ($headers['retry-after'] ?? $headers['ratelimit-reset'] ?? 2 ** $attempt)); } throw new RuntimeException('Still rate limited');}
print_r(getWithBackoff('https://api.smsfabric.com/v1/messages?limit=1'));حدود المعدل وحصص الباقة
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 (الباقات).
حدود خدمة التحقق
Section titled “حدود خدمة التحقق”لخدمة التحقق حدود خاصة لكل رقم ولكل دولة ولكل مؤسسة، ترد بالرمز 429 verify_resend_limited أو 429 verify_velocity_exceeded مع Retry-After بالثواني. مدة الانتظار هنا دقائق: اعرضها للمستخدم بدل إعادة المحاولة في حلقة. انظر التحقق من أرقام الهواتف.
البقاء ضمن الحدود
Section titled “البقاء ضمن الحدود”- استخدم webhooks بدل الاستعلام المتكرر عن حالة الرسائل.
- اجمع حتى 100 مستلم في كل إرسال (
recipientsPerRequestفي باقتك). - استخدم
limit=200عند تصفح القوائم، وlistAll()في حزمة SDK. - وزّع المهام المجدولة على الدقيقة بدل إطلاقها كلها عند الثانية صفر.
كل الحدود مذكورة في الحدود.