المرجع
حدود المعدل
تحمي الحدود API من الفيضانات لا من الموزّعين العاديين. لكل حساب حد واحد في الدقيقة يزداد مع إنفاقه، وتغطي بعض الحدود الضيقة الإجراءات الثقيلة. أما القواعد الخاصة بطلب واحد، مثل انتظار إعادة التعبئة، فتعيد رمز الخطأ الخاص بها بدل 429.
طبقات تحديد المعدل
لكل عنوان IP
20,000 طلب / دقيقة / عنوان IP
يُطبَّق قبل التحقق من المفتاح كي يكون تعداد المفاتيح بالقوة الغاشمة محدودًا. مشترك بين كل المفاتيح خلف عنوان IP نفسه. الافتراضي مضبوط عالميًا وغير قابل للتخصيص من المستخدم.
نافذة الحساب المشتركة
120–2,400 طلب / 60 ثانية متحركة
تستهلك جميع مفاتيح API النشطة في الحساب العداد نفسه. يحدد سلم الإنفاق الناجح مدى الحياة الحد ما لم يوجد تجاوز RPM مباشر.
خاص بالإجراء
يعتمد على الإجراء
لدى services وcatalog وcancel وrefill وإجراءات webhook حدودها الضيقة الخاصة، الموضحة أدناه. وهي تُضاف إلى حد الحساب ولا تحل محله.
حدود كل إجراء
تُحسب هذه الحدود لكل حساب في الدقيقة. يبيّن ردّ 429 من أحدها القيمة action في X-RateLimit-DeniedBy. يحسب cancel وrefill معرّفات الطلبات لا الطلبات HTTP، لذا فإن استدعاءً واحدًا لـ 10 طلبات يستهلك 10 من المعرّفات المتاحة لك في الدقيقة. يمرّ طلب cancel أو refill بعدد معرّفات أكبر من ذلك، حتى 100، إذا كان أول طلب لك في الدقيقة، ويستهلك الدقيقة كلها.
| الإجراء | في الدقيقة | ما الذي يُحسب |
|---|---|---|
| services | 10 | الطلبات HTTP |
| catalog | 30 | الطلبات HTTP |
| cancel | 30 | معرّفات الطلبات |
| refill | 30 | معرّفات الطلبات |
| webhook.* | 10 | الطلبات HTTP |
سلم الإنفاق الناجح مدى الحياة
يتبع حد حسابك إنفاقك الناجح التراكمي مدى الحياة؛ وتفتح الفئة الأعلى حدًا أعلى فورًا. يُطبَّق سقف عنوان IP البالغ 20,000 طلبًا في الدقيقة قبل فحص المفتاح. يستطيع المسؤول تحديد حد مباشر لحساب، حتى 10,000. فئة حسابك موجودة في ترويسة X-RateLimit-Tier وفي صفحة API الخاصة بك.
| الفئة | الحد الأدنى للإنفاق مدى الحياة | طلبات / دقيقة |
|---|---|---|
| 0 | 0 US$ | 120 |
| 1 | 10 US$ | 300 |
| 2 | 50 US$ | 600 |
| 3 | 100 US$ | 900 |
| 4 | 500 US$ | 1,200 |
| 5 | 1,000 US$ | 1,800 |
| 6 | 2,500 US$ | 2,400 |
ترويسات الاستجابة
ترويسات الاستجابة
X-RateLimit-Limit- في الاستجابات العادية، الحد الفعلي المشترك لطلبات الحساب في الدقيقة. وفي استجابة 429، الحد الذي تبلغ عنه طبقة الرفض.
X-RateLimit-Remaining- في الاستجابات العادية، الطلبات المتبقية في نافذة الحساب المشتركة. وفي استجابة 429، القيمة المتبقية التي تبلغ عنها طبقة الرفض.
X-RateLimit-Reset- عدد نسبي من الثواني حتى إعادة ضبط النافذة المُبلّغ عنها؛ وليس طابعًا زمنيًا بنظام Unix.
X-RateLimit-Tier- الفئة المكتسبة من الإنفاق الناجح مدى الحياة (0–6). لا يغيّر تجاوز RPM المخصص هذه القيمة.
X-RateLimit-DeniedBy- يُرسل مع استجابة 429 عندما يرفض محدد مسمى الطلب: "ip" أو "api_requests_per_minute" أو "action".
Retry-After- في استجابة 429 أو 503 القابلة لإعادة المحاولة، انتظر قيمة Retry-After هذه الثواني على الأقل قبل إعادة المحاولة. في action=add، استخدم مفتاح التكرار الآمن نفسه بعد الانتظار.
التعامل مع استجابات 429
انتظر وفق Retry-After عندما يكون موجودًا.
وإلا فانتظر عدد ثواني X-RateLimit-Reset. القيمتان تأخيران نسبيان لا ساعتان زمنيتان؛ أضف قدرًا عشوائيًا من التأخير قبل إعادة المحاولة.اقرأ X-RateLimit-DeniedBy.
فهو يسمّي الحد الذي رفض الاستدعاء. تغيير المفتاح لا يفيد، لأن حدود الحساب وعنوان IP والإجراء مشتركة.استخدم webhooks بدل الاستعلام المتكرر.
تصل الـ webhooks مرة واحدة على الأقل، لذا اجعل معالجك idempotent واستخدمaction=statusللتحقق من كل ما هو مهم.اجمع الطلبات حيثما أمكن.
يقبل status وcancel وrefill حتى 100 معرّفًا في الطلب الواحد؛ ويظل حساب معرّفات الطلبات ساريًا على cancel وrefill.