Ліміти й обмеження частоти

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

Обмеження частоти: десять запитів на хвилину

Обмеження діє для кожного облікового запису й спільне для API та MCP-сервера: десять викликів на хвилину, хоч би яким шляхом вони надходили. Одинадцятий запит у межах цього вікна одразу отримує 429 too_many_requests і заголовок Retry-After із кількістю секунд до звільнення місця. Те саме число є в тілі як error.retry_after.

HTTP/2 429
Retry-After: 18

{ "error": { "code": "too_many_requests",
             "message": "At most 10 requests per minute.",
             "retry_after": 18 } }

Зачекайте Retry-After секунд і повторіть запит. Нічого не списано, денний ліміт не витрачено.

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

Денний ліміт

Тариф дозволяє певну кількість пошуків на день і певну кількість запитів із фрагментами на день - вони рахуються окремо. Обидва ліміти оновлюються найближчої опівночі за UTC, а не через 24 години після використання.

Кожен пошук списує одиницю з ліміту пошуків.
Пошук із snippets=1 натомість списує одиницю з ліміту фрагментів.
/v1/account нічого не коштує.

Коли ліміт вичерпано, запит відхиляється з 429 quota_exceeded або 429 snippet_quota_exceeded, і у відповіді є ліміт, використана кількість і час до оновлення. Вичерпаний ліміт фрагментів не заважає звичайним пошукам.

Глибина результатів

Тариф також визначає, до якої позиції в рейтингу результати лишаються відкритими, - disclosed_positions з /v1/account. Рядки за цією межею пропускаються, а не замінюються порожніми, і якщо якісь пропущено, truncated у тілі дорівнює true, а в заголовках є X-Truncated: true.

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

Поточний стан

Кожна автентифікована відповідь містить п’ять заголовків:

Заголовок	Значення
`X-RateLimit-Limit`	Скільки пошуків дозволено сьогодні.
`X-RateLimit-Remaining`	Скільки пошуків залишилося на сьогодні.
`X-RateLimit-Reset`	Час Unix, коли оновиться денний ліміт.
`X-Snippets-Limit`	Скільки запитів із фрагментами дозволено сьогодні.
`X-Snippets-Remaining`	Скільки запитів із фрагментами залишилося на сьогодні.

Результати містять ще три:

Заголовок	Значення
`X-Total-Results`	Скільки сайтів відповідають запиту в усьому індексі.
`X-Returned-Results`	Скільки рядків містить ця відповідь.
`X-Truncated`	`true`, якщо ліміт глибини тарифу прибрав рядки.

Статистика використання

/v1/account дає повну картину одним викликом і нічого не витрачає:

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "disclosed_positions_snippets": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

Старіший https://publicwww.com/profile/api_status.xml?key=... повідомляє ті самі лічильники в XML і досі працює. Він належить до старих URL; новий код має використовувати /v1/account, який повідомляє й ліміти, а не лише лічильники.

Далі Помилки