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

> Стандартный формат ответов об ошибках, коды статусов HTTP и заголовки ограничения частоты.

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

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

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

```json
{
  "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 в секундах, указывающая время сброса лимита.