Ліміти запитів

Кожен API-ключ має бюджет запитів на секунду й на годину. Ліміти захищають і вас, і нас: вони не дають циклу, що вийшов з-під контролю, спустошити вашу кредитну картку й не дають жодному тенанту перевантажити регіон.

Значення за замовчуванням

Ліміти діють для кожного API-ключа окремо, а не для проєкту: якщо в одному проєкті у вас три ключі, кожен має власний бюджет. Більшість команд навіть не наближаються до ліміту рівня Production; якщо ж ви наближаєтеся, панель «rate limit usage» у дашборді покаже місця викликів, які найшвидше витрачають квоту.

Як працює обмеження

Кожен ключ має свій token bucket. Він поповнюється зі швидкістю посекундного ліміту, а його розмір підібрано так, щоб після короткого burst, який вичерпує бюджет, відновлення займало ~10 секунд. Годинний ліміт — жорстка стеля: щойно ви її досягнете, жоден запит не пройде, доки ковзне годинне вікно не зсунеться вперед.

Ліміти перевіряються на шлюзі, ще до того, як запит дійде до обробника ресурсу. Запит, обмежений лімітом, ніколи не торкається ресурсів вашого проєкту, тож нічого вам не коштує, крім запису про невдалий запит у журналі.

Заголовки відповіді

Кожна відповідь API містить чотири заголовки з даними про ваш поточний бюджет:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1763410812
X-RateLimit-Window: 1

• X-RateLimit-Limit — загальний бюджет на поточне вікно
• X-RateLimit-Remaining — скільки запитів лишилося
• X-RateLimit-Reset — час Unix epoch, коли бюджет поповниться (або годинне вікно зсунеться)
• X-RateLimit-Window — 1 для посекундного бюджету, 3600 для годинного. Ми показуємо той бюджет, до вичерпання якого ви ближче

Коли Remaining доходить до нуля, наступний запит повертає 429 Too Many Requests із заголовком Retry-After (у секундах), який каже, коли повторити запит.

Стратегія backoff

Правильний патерн, коли ви отримуєте 429:

async function callWithBackoff(fn: () => Promise<Response>) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fn()
    if (res.status !== 429) return res

    const retryAfter = Number(res.headers.get('Retry-After') ?? '1')
    // Jitter prevents the thundering-herd problem if many clients
    // hit the limit at the same moment and all retry exactly together
    const jitter = Math.random() * 0.5 * retryAfter
    await new Promise(r => setTimeout(r, (retryAfter + jitter) * 1000))
  }
  throw new Error('Rate limit exceeded after 5 retries')
}

Два зауваження:

• Завжди дотримуйтеся Retry-After. Не повторюйте раніше — ви просто знову впретеся в ліміт і швидше спалите бюджет.
• Додавайте jitter, якщо викликаєте API з кількох воркерів. Без jitter усі ваші воркери повторюють запит в один і той самий момент і разом знову впираються в ліміт.

Що вважається запитом

Кожен HTTP-виклик API зараховується як один запит, зокрема:

• GET-запити (так, навіть GET /v1/regions)
• Виклики пагінації (кожна сторінка — окремий запит)
• Ідемпотентні повтори (влучання в кеш теж зараховується як один запит — але воно дешеве, а завдяки дедуплікації ви не платите за саму операцію двічі)

Що не зараховується:

• Статичні ресурси з маркетингового сайту (їх віддає CDN, а не API)
• Доставки вебхуків на ваш бік (їх надсилаємо ми, а не ви)
• Невдалі спроби підключення (у журналі шлюзу немає запису)

Як підвищити ліміти

Рівнів Starter і Production зазвичай вистачає з запасом: годинної стелі коли-небудь досягають менш ніж 5 % акаунтів. Якщо ви її досягли, звертайтеся через форму підтримки, а не через API — так само, як щодо збільшення квот. Запити щодо міграцій у продакшн обробляють того самого дня.

Якщо ви впираєтеся в посекундні ліміти, але не в годинні, підвищення зазвичай не потрібне — потрібно розподілити навантаження (обʼєднувати запити в пакети, використовувати Idempotency-Key для дедуплікації повторів, гортати сторінки розумного розміру). Панель «rate limit usage» у дашборді показує, на яких ендпоінтах трапляються сплески.

Що далі

• Угоди — формат запиту, коди статусу й загальніші патерни API.
• Ідемпотентність — патерн безпечного повтору, коли мережеві збої схожі на ліміти запитів.
• Квоти — ліміти на ресурси (VM, vCPU, сховище), на відміну від лімітів частоти запитів.