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

Elido обмежує швидкість запитів до API для кожного ключа окремо, а не для всього робочого простору. Це означає, що кожна створена вами інтеграція може використовувати свій власний ліміт, не обмежуючи інші. У цій статті описані ліміти для кожного тарифного плану, заголовки, які потрібно зчитувати, та способи коректного зменшення інтенсивності запитів.

Показники

Сталі ліміти на ключ:

План	На хвилину	Burst (пік)
Free	60	120
Pro	600	1200
Business	6000	12000

Burst — це кількість запитів, яку ви можете короткочасно перевищити в межах 10-секундного вікна. Sustained (сталий ліміт) — це постійна швидкість, з якою поповнюється ваш ліміт.

Окремих лімітів для різних кінцевих точок немає — GET /v1/links рахується так само, як і POST /v1/links. Єдиними винятками є:

• POST /v1/bulk-import — одночасно не більше 5 активних імпортів на робочий простір.
• POST /v1/links з власним slug, що збігається з існуючим — такі запити все одно враховуються, але слот не повертається у разі конфлікту.
• GET /v1/analytics/timeseries з параметром interval=second — обмежено до 60/minute навіть на плані Business, оскільки відповідний запит до ClickHouse є ресурсомістким.

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

Кожна відповідь API містить:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset — це Unix timestamp, який вказує, коли ліміт буде повністю поповнено. Використовуйте його для планування повторних спроб замість фіксованих затримок.

Як виглядає помилка 429

Коли ви перевищуєте ліміт:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After вказано у секундах. Зачекайте цей час, а потім повторіть запит. SDK роблять це автоматично з використанням джитера (jitter); якщо ви пишете власний HTTP-клієнт, робіть так само.

Стратегія відкладених запитів (backoff)

Якщо ви виконуєте велику кількість запитів (разове масове завдання, заповнення даних), налаштуйте свій клієнт на сталу швидкість (sustained limit), а не на пікову (burst). Примітивний цикл швидко вичерпає піковий ліміт, потім зупиниться на 50 секунд, а потім знову досягне піку — середня швидкість при цьому буде гіршою, ніж при рівномірному розподілі запитів.

Псевдокод:

const limit = 600; // per minute
const delayMs = (60 * 1000) / limit; // 100ms between requests

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Така модель використовує 100% ліміту без жодних помилок 429.

Конкурентність

Паралельні запити використовують спільний ліміт. Якщо ви запустите 100 паралельних запитів з пулу воркерів на плані Pro (600/min), перші 100 виконаються миттєво; після цього ліміт поповнюватиметься зі швидкістю 10/sec. Ваш пул воркерів має орієнтуватися на сталу швидкість, а не на глибину черги.

На ключ чи на IP

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

Рівень IP має окремий, дуже великий ліміт (10,000/min/IP), призначений лише для зупинки некоректно працюючих клієнтів. Ви ніколи не досягнете його за нормального використання; якщо ж це станеться, ви отримаєте відповідь 429 із тілом "error": "ip_rate_limited".

Idempotency keys не обходять ліміт

Надсилання того самого Idempotency-Key кілька разів все одно зараховується як окремі запити — ми можемо повернути кешовану відповідь без виконання основної роботи, але лічильник запитів збільшується. Не використовуйте цикли з ключами ідемпотентності як стратегію повторних спроб.

Збільшення лімітів

Якщо ваш випадок використання дійсно потребує понад 6000/min постійно, напишіть на [email protected], вказавши:

• ID вашого робочого простору.
• Назву інтеграції.
• Очікувану сталу та пікову швидкість запитів.
• Які кінцеві точки ви використовуєте (щоб ми могли спланувати потужності для складних запитів).

Ми надаємо індивідуальні підвищення лімітів для корпоративних клієнтів за контрактом, зазвичай протягом одного робочого дня.

Усунення несправностей

Раптово почали з'являтися помилки 429 для ключа, який раніше працював. Або ваш код потрапив у нескінченний цикл (найчастіша причина), або хтось інший у вашому робочому просторі почав використовувати той самий ключ. Перевірте вкладку Usage для API-ключа на панелі керування, щоб побачити щохвилинний графік.

Помилки 429 під час першого запиту за день. Ліміти на безкоштовному тарифі скидаються за ковзним вікном, а не о півночі за UTC. Якщо ви вичерпали ліміт вчора о 23:59 і він ще не встиг повністю відновитися до 00:01, перший піковий запит все одно буде обмежений. Зачекайте 60 секунд.

X-RateLimit-Remaining має від'ємне значення. Перевищення пікового ліміту (burst). Це число показує, наскільки ви пішли «в мінус»; помножте його на 60/limit, щоб дізнатися, через скільки секунд значення повернеться до нуля.