Ошибки и лимиты API платформы

Ошибки API платформы имеют другую структуру тела, чем ошибки эндпоинтов моделей: результат определяется HTTP-статусом, а JSON-тело всегда содержит success и, при ошибке, машиночитаемый code.

Формат ответа

При успехе возвращается HTTP 200:

{
  "success": true,
  "message": "",
  "data": {}
}

При ошибке используется реальный HTTP-код статуса, а тело содержит машиночитаемый code:

{
  "success": false,
  "message": "Invalid Management Key",
  "code": "invalid_token"
}

message локализуется и может меняться между версиями. В логике программы используйте HTTP-код статуса и code.

Коды ошибок

HTTP	code	Сценарий
400	invalid_request	Неверные параметры: сумма вне допустимого диапазона, отсутствующее или слишком длинное имя при создании, status не 1 / 2, включение Key, который ещё истёк или исчерпан, неверный срок действия, неверная пагинация или временной диапазон, либо необработанный ; в query
401	invalid_token	Отсутствует заголовок Authorization, Key имеет неверный формат, не найден или удалён
401	token_expired	Срок действия ключа управления истёк
401	token_revoked	Ключ управления отозван (только для существующих ключей; новые ключи можно только удалить)
403	user_disabled	Аккаунт владельца ключа управления отключён
403	insufficient_scope	У ключа управления нет разрешения, необходимого для этого эндпоинта
404	not_found	API Key не существует или не принадлежит вам (без различия); или путь не существует под /api/open/v1
405	method_not_allowed	Путь существует, но не поддерживает этот HTTP-метод
429	rate_limited	Превышен лимит запросов на ключ управления
500	internal_error	Ошибка сервера; внутренние детали не возвращаются

Неизвестные пути под /api/open/v1 возвращают 404, а неправильный HTTP-метод — 405; в обоих случаях используется единое тело ошибки выше. По code можно отличить «повторить с другим методом» от «неверный путь или параметры».

Ограничения частоты

Область	Лимит	Применяется к	Ответ при превышении
На ключ управления	120 запросов/минуту	Все эндпоинты API платформы	429, code равен rate_limited
На пользователя	30 запросов/минуту (по умолчанию)	Логи аккаунта, Экспорт логов, Использование, Использование по моделям, Использование по Key	429, тело может быть пустым
На IP клиента	180 запросов/180 секунд (по умолчанию)	Общий для всех эндпоинтов /api	429
На IP клиента	100 запросов/20 минут (по умолчанию)	Чувствительные эндпоинты, например Получить полный API Key	429, тело может быть пустым

Обрабатывайте ограничение частоты по HTTP-коду статуса. Получив 429, снизьте частоту и повторите запрос позже.

Эндпоинты моделей используют другой формат ошибок и отдельные лимиты; см. Частые ошибки.