## Настроить авто-сон

`PATCH /v1/infra/servers/:id/sleep`

Настраивает таймер автоматического засыпания BLACKHOLE-сервера. При отсутствии входящих HTTP-запросов к приложению в течение `sleepAfterMinutes` минут сервер автоматически останавливается. Поднять его снова можно вызовом [`/wake`](./wake.md), а обращение к HTTPS-субдомену будит сервер не в каждом случае — условия там же. Передача `null` отключает авто-сон.

`null` отключает только наш авто-сон по бездействию. Если сервер стоит на **вытесняемом (preemptible)** тарифе (`bc-agent`, `bc-micro` — см. [Тарифы](/docs/infra/providers/plans)), облако всё равно принудительно перезапускает такую машину примерно раз в сутки, с коротким окном недоступности. Платформа автоматически будит её обратно. Для по-настоящему непрерывной 24/7-нагрузки выбирайте **невытесняемый** тариф (`bc-small` и выше) — на нём `null` действительно означает работу до ручной остановки.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | да | ID сервера в режиме BLACKHOLE |

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `sleepAfterMinutes` | number \| null | **да** | Таймаут простоя в минутах. Допустимые значения: `15`, `30`, `60`, `240`, или `null` (для отключения авто-сна). Другие значения отклоняются с `VALIDATION_ERROR` |

## Примеры

### curl — личный ключ

```bash
# Включить авто-сон через 60 минут простоя
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": 60}'

# Отключить авто-сон
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": null}'
```

### curl — OAuth-приложение

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": 60}'
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/sleep`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sleepAfterMinutes: 60 }),
  }
)
const { data } = await res.json()
console.log(`Авто-сон через ${data.sleepAfterMinutes} мин`)
```

### JavaScript — OAuth-приложение

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/sleep`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sleepAfterMinutes: null }),
  }
)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.sleepAfterMinutes` | number \| null | Актуальное значение таймаута (эхо переданного) |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "sleepAfterMinutes": 60
  }
}
```

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

400 — некорректное значение `sleepAfterMinutes`:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "sleepAfterMinutes must be 15, 30, 60, 240, or null"
  }
}
```

400 — сервер не в BLACKHOLE:

```json
{
  "success": false,
  "error": {
    "code": "BLACKHOLE_ONLY",
    "message": "Sleep settings are only available for BLACKHOLE servers"
  }
}
```

400 — переход в «Всегда онлайн» при включённых окнах пробуждения:

```json
{
  "success": false,
  "error": {
    "code": "ALWAYS_ON_CONFLICT",
    "message": "The server has enabled wake-schedule windows, which conflict with always-on (24/7) mode. Delete or disable the wake windows first, or keep a sleep timeout."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | `sleepAfterMinutes` не в списке `[15, 30, 60, 240, null]` |
| 400 | `GALAXY_APP_USE_GALAXY_ROUTE` | Сервер — galaxy-приложение. Оно засыпает вместе с хостом, таймер простоя через API Вайбкод ему не задаётся. Что применимо к приложению — [Galaxy-приложение](/docs/infra/galaxy) |
| 400 | `BLACKHOLE_ONLY` | Сервер в режиме `OPEN` — авто-сон недоступен |
| 400 | `ALWAYS_ON_CONFLICT` | `null` на невытесняемом тарифе при включённых [окнах пробуждения](/docs/infra/wake-schedules) — сначала удалите или отключите окна |
| 400 | `AGENT_IDLE_SLEEP_FORBIDDEN` | Сервер создан под агента или бота (`createdVia` agent/bot) — числовой `sleepAfterMinutes` запрещён, принимается только `null`. Экономия по расписанию — через окна пробуждения |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 403 | `SERVER_ROLE_FORBIDDEN` | Вы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В `error.hint` придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — [Список серверов](/docs/infra/servers/list) |
| 404 | `NOT_FOUND` | Сервер не существует, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- **Что считается активностью и сбрасывает таймер.** Таймер сбрасывают входящие HTTP-запросы к приложению через туннель. Реальная активность проверяется раз в несколько минут через Gateway-метрики, момент последнего обращения виден полем `lastRequestAt` в [`GET /v1/infra/servers/:id/metrics`](/docs/infra/deploy/metrics). Запросы, которые приложение отправляет само наружу, активностью не считаются, поэтому приложение с постоянным опросом внешнего API собственную машину в сети не удерживает и через `sleepAfterMinutes` минут останавливается вместе с ней. Для такого приложения авто-сон отключают значением `null`.
- **Авто-пробуждение сохраняется.** Сервер, заснувший по таймеру, просыпается при вызове [`/deploy`](/docs/infra/deploy/deploy)/[`/wake`](./wake.md)/[`/start`](./start.md), а обращение к HTTPS-субдомену будит его на [условиях автоматического пробуждения](./wake.md).
- **Значение по умолчанию для новых серверов** — 60 минут. Текущее значение — в поле [`GET /v1/infra/servers/:id`](/docs/infra/servers/get).
- **Серверы агентов и управляемых ботов не засыпают по простою.** Речь о машинах, которые платформа создаёт сама под AI-агента или управляемого бота, — в ответе [`GET /v1/infra/servers/:id`](/docs/infra/servers/get) у них поле `createdVia` равно `agent` или `bot`. Машина, которую вы создали через [`POST /v1/infra/servers`](/docs/infra/servers/create), под это правило не подпадает: у неё `createdVia` равно `api`, таймаут простоя по умолчанию 60 минут, и собственного бота на такой машине от засыпания защищаете вы сами — значением `null`. Серверы агентов и управляемых ботов создаются с `sleepAfterMinutes: null` и должны оставаться в сети круглосуточно: спящий бот перестаёт опрашивать Битрикс24 и не проснётся на новое сообщение, а выполняемая задача оборвётся. Поэтому для сервера, созданного под агента или бота, запрос с числовым `sleepAfterMinutes` отклоняется — `400 AGENT_IDLE_SLEEP_FORBIDDEN`. Принимается только `null` (никогда не засыпать). Для экономии по расписанию используйте [окна пробуждения](/docs/infra/wake-schedules). Для обычных приложений `null` тоже допустим, но приведёт к постоянному списанию по рабочему тарифу — по умолчанию агент/бот создаётся на вытесняемом тарифе — он дешевле, и облако перезапускает такую машину примерно раз в сутки. Для непрерывной работы включите «Всегда онлайн» при создании, это невытесняемый тариф.
- **Взаимное исключение с расписанием пробуждения.** `sleepAfterMinutes: null` на невытесняемом тарифе означает «Всегда онлайн» — такой сервер несовместим с включёнными [окнами пробуждения](/docs/infra/wake-schedules): запрос отклоняется с `ALWAYS_ON_CONFLICT`. Верно и обратное — окно нельзя объявить на сервере «Всегда онлайн». Сначала удалите или отключите окна, либо оставьте числовой таймаут.
- **Эндпоинт не меняет статус** — только обновляет конфигурацию. Чтобы усыпить сервер сразу, используйте [`POST /sleep-now`](./sleep-now.md).

## Смотрите также

- [Усыпить сейчас](./sleep-now.md)
- [Запустить сервер](./start.md)
- [Метрики сервера](/docs/infra/deploy/metrics)
- [Тарифы провайдера](/docs/infra/providers/plans)
- [Получить сервер](/docs/infra/servers/get)