## Усыпить сейчас

`POST /v1/infra/servers/:id/sleep-now`

Немедленно усыпляет работающий BLACKHOLE-сервер: виртуальная машина останавливается у провайдера, статус меняется на `sleeping`, рабочая биллинг-транзакция финализируется и открывается сонная (тариф sleep ниже). Полезно для разовой экономии, когда вы знаете, что сервер не понадобится в ближайшие часы. Для автоматической остановки через N минут простоя используйте [`PATCH /sleep`](./sleep.md).

## Параметры

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

Тело запроса пустое.

## Примеры

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

```bash
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep-now
```

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

```bash
curl -X POST -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/sleep-now
```

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

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/sleep-now`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
```

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

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/sleep-now`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` и при усыплении, и при отложенном усыплении |
| `data` | object | Приходит только при отложенном усыплении. При успешном переходе в `sleeping` блока `data` в ответе нет |
| `data.slept` | boolean | Всегда `false` — сервер остался в статусе `running` |
| `data.reason` | string | Причина отказа. Единственное значение — `WAKE_IMMINENT` |

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

Сервер переведён в `sleeping`:

```json
{ "success": true }
```

Усыпление отложено — ближайшее окно [пробуждения по расписанию](/docs/infra/wake-schedules) уже на подходе:

```json
{
  "success": true,
  "data": {
    "slept": false,
    "reason": "WAKE_IMMINENT"
  }
}
```

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

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

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `BLACKHOLE_ONLY` | Сервер в режиме `OPEN`. Для OPEN-серверов используйте [`/stop`](./stop.md) |
| 400 | `GALAXY_APP_USE_GALAXY_ROUTE` | Сервер — galaxy-приложение. Оно засыпает вместе с хостом. Код приходит в любом статусе приложения, `NOT_RUNNING` вместо него не возвращается — [Galaxy-приложение](/docs/infra/galaxy) |
| 400 | `NOT_RUNNING` | Сервер не в статусе `running` (уже спит, в ошибке или создаётся) |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 404 | `NOT_FOUND` | Сервер не существует или принадлежит другому API-ключу |
| 409 | `CONFLICT` | Гонка состояний — статус сервера изменился во время операции |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

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

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

- **На OPEN-сервере используйте [`/stop`](./stop.md).** Функционально для BLACKHOLE `/sleep-now` и `/stop` эквивалентны, но `/sleep-now` помечен как BH-специфический и для OPEN вернёт `BLACKHOLE_ONLY`.
- **Автоматическое пробуждение сохраняется.** В отличие от административного блока `preventWake=true`, ручной `/sleep-now` запрет не ставит: сервер поднимут вызовы [`/deploy`](/docs/infra/deploy/deploy) и [`/wake`](./wake.md), а обращение к HTTPS-субдомену — на описанных там условиях.
- **Серверы агентов и ботов остаются с запретом на пробуждение.** У сервера, созданного через агента или бота, ручной вызов проставляет `preventWake: true` и причину `AGENT_STOPPED` либо `BOT_STOPPED` — разбудить его сможет только `/start` соответствующей карточки. У обычных серверов запрет не ставится.
- **Атомарный переход.** База обновляется одним `updateMany` с фильтром `status='RUNNING'` — гонки двух одновременных вызовов приводят ко второму `CONFLICT`, а не к двойному списанию.
- **Сервер с окном пробуждения по расписанию может отложить усыпление.** Ветка `WAKE_IMMINENT` включается только у сервера, которому создано окно [пробуждения по расписанию](/docs/infra/wake-schedules). Платформа сверяет ближайшее окно с текущим моментом: если оно наступит в пределах платформенного запаса (по умолчанию 5 минут) или наступило только что, усыпление отменяется, чтобы платформа не гасила машину прямо перед подъёмом. Ответ приходит со статусом `200` и полями `slept: false`, `reason: "WAKE_IMMINENT"` — сервер остался в статусе `running`. Повторите вызов после отработки окна. У сервера без окон и у портала, которому пробуждение по расписанию недоступно, эта ветка не срабатывает: усыпление проходит сразу.

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

- [Настроить авто-сон](./sleep.md)
- [Остановить сервер](./stop.md)
- [Запустить сервер](./start.md)
- [Разбудить сервер](./wake.md)