محدودیت‌ها و سهمیه‌ها

هر درخواستی که با کلید فرستاده شود، مشمول دو سقف است: محدودیت نرخ (تعداد درخواست در دقیقه، همراه با ظرفیتی کوتاه برای جهش) و سهمیهٔ روزانهٔ سازمان (طبق پلن آن). درخواست‌های بی‌نام در یک محدودیت نرخ به ازای هر نشانی کلاینت شریک‌اند.

محدودیت‌های نرخ

وقتی به یک محدودیت برسید، API با 429 همراه با Retry-After (بر حسب ثانیه) و کد rate_limited پاسخ می‌دهد. همان‌قدر صبر کنید و بعد ادامه دهید. اگر چند پردازه (worker) از یک کلید استفاده می‌کنند، کمی تأخیر تصادفی (jitter) اضافه کنید.

سهمیه‌های روزانه

کلیدها و توکن‌های OAuth یک سازمان در یک سهمیهٔ روزانه شریک‌اند که پلن آن تعیین می‌کند (در پلن رایگان ۱۰٬۰۰۰ درخواست در روز). سهمیه در طول روز به‌طور یکنواخت پر می‌شود. وقتی تمام شود، درخواست‌ها پاسخ 429 با کد quota_exceeded و Retry-After می‌گیرند.

مصرف

درخواست‌ها به ازای هر کلید و هر روز شمرده می‌شوند. GET /v1/orgs/{org_id}/api-usage?month=YYYY-MM مصرف یک ماه را به ازای هر کلید و هر کلاینت OAuth (توکن‌های یک‌ساعتهٔ هر کلاینت با هم شمرده می‌شوند) در کنار سهمیهٔ روزانه جمع می‌زند؛ GET /v1/orgs/{org_id}/api-keys/{key_id}/usage مصرف روزبه‌روز یک کلید را می‌دهد. وقتی پلنی برای استفاده از API هزینه تعیین کند، صورتحساب‌ها از همین شمارش‌ها ساخته می‌شوند.

یک کلاینت خوب باشید

• آنچه را می‌خوانید کش کنید. صفحه‌های شرکت آهسته تغییر می‌کنند؛ Cache-Control می‌گوید یک پاسخ عمومی تا کی تازه می‌ماند.
• برای رویدادهای سازمانتان، وب‌هوک را به پرس‌وجوی پیاپی (polling) ترجیح دهید.
• 429 و 5xx را با فاصلهٔ فزاینده (backoff) دوباره امتحان کنید؛ دیگر خطاهای 4xx را بدون تغییر دادن درخواست تکرار نکنید.