Как работают ограничения запросов к API Vista Social

Vista Social ограничивает частоту запросов, чтобы платформа оставалась быстрой и справедливой для всех рабочих пространств. В этой статье описано, какие есть ограничения, как понять, что вы к ним приближаетесь, и что делать, если вы упёрлись в лимит.

Если у вас всего минута, вот краткая версия:

• Лимит по умолчанию: 60 запросов в минуту на одну интеграцию. У интеграции MCP (ChatGPT / Claude / Cursor и т. д.) лимит выше: 180 запросов в минуту.
• У каждой интеграции свой бюджет. Работа через Zapier не замедляет ваши прямые вызовы API (и наоборот).
• В каждом ответе мы точно показываем, сколько у вас осталось, в трёх заголовках: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• Если вы превысите лимит, вы получите ответ HTTP 429 с заголовком Retry-After, где указано, сколько секунд нужно подождать.

Это 90% того, что нужно большинству. Остальная часть статьи раскрывает подробности.

Где действуют ограничения

Каждая строка означает отдельный бюджет. Рабочее пространство, которое использует Zapier, и напрямую вызывает REST API, и подключает ИИ-ассистента с поддержкой MCP, имеет три независимых бюджета, а не один общий. Выбирайте подходящую интеграцию для каждой задачи, и лимит будет заканчиваться редко.

На тарифах Enterprise можно повысить поминутный лимит интеграций. Если вашему бизнесу нужен более высокий лимит, свяжитесь с вашим аккаунт-менеджером Vista Social: мы можем увеличить его для отдельного рабочего пространства.

Как читать заголовки лимитов

Каждый ответ от /api/integration/* (включая успешные) содержит три заголовка с текущим состоянием вашего bucket:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1716480123

Если вы строите автоматизацию на API Vista Social, самый простой способ избежать проблем: читать X-RateLimit-Remaining и делать паузу, когда значение становится маленьким (например, меньше 5), пока не наступит X-RateLimit-Reset.

Значения выше указаны по умолчанию, реальные значения зависят от вашей подписки. Всегда ориентируйтесь на заголовки, а не на документацию.

Если вы превысили лимит

Вы получите ответ HTTP 429 Too Many Requests.

Заголовки ответа:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716480123
Retry-After: 24
Content-Type: application/json

Тело ответа:

{
  "error": "You are going too fast, please slow down. 60 requests are allowed every minute per integration.",
  "errorValues": { "value1": 60 }
}

Что делать:

1. Прочитайте Retry-After. Это число (в примере 24) показывает время ожидания в секундах, пока ваш bucket не пополнится настолько, чтобы принять следующий запрос.
2. Подождите не меньше этого времени перед повтором. Стандартные HTTP-клиенты (axios, requests в Python, Postman и т. д.) автоматически учитывают Retry-After, если настроены повторять запрос после 429.
3. Не повторяйте запрос раньше, чем указано в Retry-After. Это приведёт только к новым ответам 429 и вызовет оповещения о повторных нарушениях, описанные ниже.

Повторные нарушения

Превысить лимит один-два раза нормально, например, когда скрипт запускается и прогревает кэш. Но если ваша интеграция продолжает превышать лимит, мы принимаем меры:

Если ваш ключ деактивирован, устраните причину (обычно это бесконечный цикл в скрипте) и обратитесь в поддержку, чтобы его активировать снова. Счётчик сбрасывается через час после последнего нарушения.

Особенности интеграций

Прямой REST API

Стандартный bucket на 60 запросов в минуту. Эндпоинты находятся по адресу https://vistasocial.com/api/*; полный справочник есть на apidocs.vistasocial.com. Для аутентификации передавайте API-ключ в заголовке x-api-key. Указывать интеграцию не нужно.

Zapier / Make / n8n

Каждая платформа работает в своём bucket. Добавляйте заголовок api_client в свои запросы, чтобы мы понимали, от какой интеграции пришёл вызов: api_client: zapier, api_client: make или api_client: n8n. (Для n8n можно также отправлять User-Agent: n8n, его мы тоже распознаём.) Без такой подсказки запрос попадает в bucket прямого REST API и делит бюджет с вашими собственными вызовами API.

(Если вы используете наши готовые приложения для Zapier / Make / n8n, это делается автоматически.)

MCP (ChatGPT, Claude, Cursor и т. д.)

Для интеграций MCP действуют два лимита одновременно:

• Поминутный лимит (эта статья): 180 запросов в минуту в канале mcp. Он выше стандартных 60 в минуту для других интеграций, потому что ИИ-ассистенты часто отправляют запросы пачками и не всегда подстраиваются под стандартный лимит.
• Лимит всплесков для каждого инструмента (внутри MCP): у каждого инструмента есть ещё и свой краткосрочный лимит. Ресурсоёмкие инструменты, такие как generateImage и generateVideo, ограничены сильнее (например, 10 за всплеск / 5 в минуту для generateImage); для лёгких инструментов действует щедрое значение по умолчанию. Когда инструмент превышает свой лимит, ИИ-ассистент получает в ответе структурированную ошибку "rate limited" и указание подождать перед повтором.

Настраивать ничего не нужно: оба лимита применяются автоматически. Лимит на инструмент в основном срабатывает у ассистентов, которые пытаются сгенерировать большие партии медиафайлов в одном разговоре; при обычной смешанной работе с инструментами до него почти не доходит.

Приложения OAuth

Трафик с аутентификацией OAuth использует bearer-токены вместо API-ключей, но действует тот же бюджет 60 запросов в минуту для рабочего пространства, которое выдало авторизацию.

Частые вопросы

«Я делаю намного меньше 60 запросов в минуту, почему я получаю 429?»

Проверьте несколько моментов:

1. Другие интеграции используют тот же API-ключ? Если несколько скриптов используют один ключ, они делят один bucket. По возможности используйте отдельный API-ключ для каждой интеграции.
2. Вы передаёте api_client? Zap в Zapier и собственный скрипт, использующие один API-ключ без заголовка api_client, попадают в один bucket direct. Добавьте заголовок на стороне Zapier, чтобы их разделить.
3. Всплеск в начале минуты? Окно сбрасывается в начале каждого цикла «первого запроса», а не на границе минуты по часам. Распределяйте запросы равномерно в течение минуты, а не отправляйте их все в первую секунду.

«Можно ли повысить мой лимит?»

Для рабочих пространств на платном тарифе Vista Social можно: свяжитесь с аккаунт-менеджером или создайте обращение, и мы рассмотрим запрос. Для бесплатных рабочих пространств лимит повысить нельзя, но оформить подписку можно в любой момент.

«Массовые операции считаются как один запрос или как несколько?»

Один HTTP-запрос = одна единица, независимо от объёма данных. POST /publishing/posts, который планирует публикацию в 10 профилей, считается как 1 запрос, а не 10.

«Запросы GET учитываются в том же bucket, что и POST / PUT?»

Да, лимит считается по запросам, а не по типу операции. Чтение и запись делят один бюджет 60 запросов в минуту в каждой интеграции.

«Где посмотреть текущее использование лимита?»

В заголовках ответа каждого вызова API. Отдельной панели для этого сейчас нет; заголовки остаются единственным достоверным источником.

«Что делать, если мой API-клиент не поддерживает Retry-After автоматически?»

Просто прочитайте Retry-After из ответа 429 и вызовите sleep(N) (или аналог) перед повтором. Любой HTTP-клиент это позволяет, просто не везде это происходит автоматически.

Всё ещё не получается?

Обратитесь в поддержку Vista Social и укажите:

• Название вашего рабочего пространства или ID корневой сущности
• Интеграцию, которую ограничивают (zapier, mcp и т. д.)
• Пример тела ответа 429 (чтобы мы проверили, какой bucket задействован)
• Время последнего ответа 429

Дальше мы разберёмся сами.