## Остановить сервер

`POST /v1/infra/servers/:id/stop`

Штатная остановка работающего сервера. Виртуальная машина останавливается у провайдера, статус меняется на `sleeping`, открытая биллинг-транзакция по рабочему периоду закрывается, открывается транзакция по сонному периоду (тариф sleep существенно ниже). Работает для любого режима — и BLACKHOLE, и OPEN. Сервер можно снова запустить через [`POST /start`](./start.md), а обращение к субдомену будит его на [условиях автоматического пробуждения](./wake.md).

## Параметры

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

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

## Примеры

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

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

### 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/stop
```

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

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

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

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

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешной остановке |

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

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

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

422 — сервер существует, но не в статусе `running` (например, `sleeping`). В ответе — текущее состояние и доступные действия:

```json
{
  "success": false,
  "error": {
    "code": "SERVER_WRONG_STATE",
    "message": "Server is SLEEPING; /stop requires RUNNING.",
    "userMessage": "Server is currently SLEEPING. Stop only applies to a RUNNING server.",
    "currentState": { "status": "sleeping", "blackholeStatus": "DISCONNECTED", "hasExternalId": true },
    "availableActions": ["wake", "start", "repair", "delete"]
  }
}
```

404 — сервера с таким `id` нет (удалён или принадлежит другому API-ключу):

```json
{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Server not found"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 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 | `SERVER_NOT_FOUND` | Сервера с таким `id` нет — удалён или принадлежит другому API-ключу |
| 422 | `SERVER_WRONG_STATE` | Сервер существует, но не в статусе `running`. В `error.currentState` — текущее состояние, в `error.availableActions` — что можно сделать сейчас |
| 422 | `VM_MISSING` | У серверной записи нет облачной ВМ: создание не завершилось или ВМ удалена вручную — удалите сервер и создайте заново |
| 422 | `VM_MISSING` | Сервер — galaxy-приложение в статусе `running`. У контейнера своей ВМ нет, останавливать нечего: чтобы снять приложение, вызовите [`DELETE /v1/infra/servers/:id`](/docs/infra/servers/delete). Пересоздавать приложение не нужно, что к нему применимо — [Galaxy-приложение](/docs/infra/galaxy) |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |
| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при остановке |

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

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

- **Почему `sleeping`, а не `stopped`.** Это терминология Infrastructure API: остановленный сервер называется «спящим», потому что списание за него идёт по отдельной ставке сна — ниже, чем за работающий. Цену сна по тарифам показывает поле `sleepPriceMonthly` в [тарифах провайдера](/docs/infra/providers/plans). Это справочная цена тарифа, а фактическая ставка списания берётся из каталога услуг платформы и может от неё отличаться. Значение `stopped` в v1-ответах не встречается.
- **`/stop` сбрасывает `preventWake`** — автоматический флаг, блокирующий пробуждение. После остановки сервер снова поднимает [`/wake`](./wake.md), а обращение к субдомену будит его на описанных там условиях.
- **Для BLACKHOLE есть альтернатива — [`/sleep-now`](./sleep-now.md).** Функционально результат идентичный. `/sleep-now` используется из UI-кнопки «Усыпить» и явно помечен как BH-специфический. `/stop` — универсальный для любого режима.

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

- [Запустить сервер](./start.md)
- [Немедленно усыпить](./sleep-now.md)
- [Настроить авто-сон](./sleep.md)
- [Удалить сервер](/docs/infra/servers/delete)