Ошибки и лимиты

Все ответы с ошибками REST API возвращаются в унифицированном формате JSON с соответствующим HTTP-кодом состояния.

Формат ответа об ошибке

При возникновении ошибки тело ответа содержит объект error:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Превышен лимит запросов",
    "request_id": "4b68e210ac124b868e826b5278c5208f",
    "details": {}
  }
}

Поля объекта ошибки:

• code: строковый машиночитаемый идентификатор ошибки.
• message: понятное описание ошибки.
• request_id: уникальный идентификатор запроса для отслеживания в логах. Значение совпадает с заголовком X-Request-ID.
• details: объект с дополнительными параметрами ошибки.

Коды состояния HTTP

Код	Описание	Типичные значения code
400 Bad Request	Некорректный синтаксис запроса или неверные параметры.	invalid_cloud_request, invalid_source_metadata, invalid_pagination
401 Unauthorized	Отсутствует, поврежден или недействителен персональный ключ API.	invalid_api_key, authentication_required
402 Payment Required	Превышен лимит дисковой квоты тарифа.	insufficient_quota
403 Forbidden	Недостаточно прав для выполнения действия или запрещенная операция.	insufficient_scope, agent_sync_not_allowed, tenant_owner_required
404 Not Found	Запрашиваемый файл, маршрут или ключ не найден.	not_found
409 Conflict	Конфликт состояния объекта (например, попытка повторной фиксации).	conflict
429 Too Many Requests	Превышен порог частоты запросов к API метаданных.	rate_limit_exceeded
503 Service Unavailable	Временная недоступность шлюза хранилища или сервиса.	cloud_unavailable

Заголовки ограничения частоты

Эндпоинты метаданных ограничивают частоту до 120 запросов в минуту на один ключ.

При получении ответа со статусом 429 клиенту передаются следующие заголовки:

• Retry-After: число секунд до момента, когда можно повторить запрос.
• RateLimit-Limit: максимальное количество запросов за фиксированное окно (120).
• RateLimit-Remaining: количество оставшихся запросов в текущем окне (0).
• RateLimit-Reset: временная метка Unix в секундах, указывающая время сброса лимита.