## Разбудить сервер

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

Пробуждает сервер из `sleeping` или `provisioning`. В отличие от [`/start`](./start.md), `/wake` поддерживает блокирующий режим через `?wait=true` — ответ возвращается только когда сервер полностью готов (виртуальная машина запущена **и** туннель подключился) или сработал таймаут. Пока платформа ждёт, она сама переспрашивает облако о состоянии машины и повторяет команду запуска, если та не доехала. Подключённый туннель считается доказательством готовности, даже если статус сервера ещё не успел обновиться. Используйте блокирующий режим, когда клиенту нужна готовность перед следующим шагом (cron-задача, триггерный вызов), и асинхронный — когда можно подождать на опросе.

## Параметры

| Параметр | В | Тип | Обяз. | По умолч. | Описание |
|----------|---|-----|:-----:|-----------|----------|
| `id` | path | string (UUID) | да | — | ID сервера в статусе `sleeping` или `provisioning` |
| `wait` | query | string | нет | — | `true` — блокирующий режим: ответ вернётся только когда сервер готов (до 6.5 минут) или сработает таймаут. Любое другое значение — асинхронный режим, ответ сразу |

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

## Примеры

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

```bash
# Асинхронный вызов — ответ сразу, готовность проверяйте опросом
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/wake

# Блокирующий — ждёт готовности до ~6.5 минут
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/wake?wait=true"
```

### 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/wake?wait=true"
```

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

```javascript
// Блокирующий вариант — проще всего для последующих шагов
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/wake?wait=true`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const body = await res.json()
if (!body.success) {
  // Rich-error: показать пользователю userMessage, предложить alternatives
  console.error(body.error.userMessage ?? body.error.message)
  if (body.error.alternatives) console.log('Варианты:', body.error.alternatives)
  throw new Error(body.error.code)
}
console.log(`Сервер готов: ${body.data.appUrl}`)
```

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

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

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешном пробуждении |
| `data.id` | string (UUID) | ID сервера |
| `data.status` | string | Актуальный статус в нижнем регистре (`running` при `wait=true` успехе, `provisioning` в асинхронном режиме) |
| `data.blackholeStatus` | string | Состояние туннеля (`CONNECTED` в блокирующем при успехе) |
| `data.appUrl` | string \| null | HTTPS-адрес приложения |

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

Успешное пробуждение (`?wait=true`):

```json
{
  "success": true,
  "data": {
    "id": "e765edfc-ba0a-43de-b8ea-838dd872c522",
    "status": "running",
    "blackholeStatus": "CONNECTED",
    "appUrl": "https://app-05b67cf7.vibecode.bitrix24.tech"
  }
}
```

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

402 — коммерческий тариф обязателен (расширенный формат ошибки для AI-агентов):

```json
{
  "success": false,
  "error": {
    "code": "COMMERCIAL_PLAN_REQUIRED",
    "message": "Waking this server requires a commercial Bitrix24 plan or an active trial",
    "userMessage": "Для пробуждения сервера нужен коммерческий тариф Битрикс24 или активный trial. Оформите тариф на https://www.bitrix24.ru/prices/",
    "alternatives": [
      "Обновить тариф Битрикс24 и повторить",
      "Перейти на AI Router с BYOK-ключами — он работает на любом тарифе"
    ],
    "hint": "Не повторяйте автоматически — нужно действие пользователя"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 402 | `COMMERCIAL_PLAN_REQUIRED` | Бесплатный тариф и trial недоступен — обновите тариф Битрикс24 |
| 402 | `TRIAL_EXPIRED` | Trial использован и завершился |
| 402 | `BILLING_EXHAUSTED` | Баланс Вайбкод исчерпан — пополните |
| 402 | `ACCOUNT_FROZEN` | Баланс заморожен |
| 403 | `SERVER_WAKE_BLOCKED` | Пробуждение заблокировано не из-за биллинга (завершённый trial, административный блок, нарушения безопасности). У galaxy-приложения тем же кодом отвечает запрет пробуждения на хосте-галактике |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 404 | `NOT_FOUND` | Сервер не в статусе `sleeping`/`provisioning`, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| 404 | `GALAXY_HOST_NOT_FOUND` | Galaxy-приложение: хост-галактика, на которой оно размещено, не найдена |
| 422 | `VM_MISSING` | У записи нет `externalId` — виртуальная машина не создана у провайдера. Удалите сервер и создайте новый |
| 422 | `SERVER_WRONG_STATE` | Galaxy-приложение, код которого ни разу не загружали, либо приложение в статусе `error`: `/wake` не восстанавливает упавшую сборку. В `error.message` — вызов загрузки кода, которым это лечится |
| 422 | `CREDENTIAL_MISSING` | Galaxy-приложение: у хоста-галактики нет привязанного доступа к облачному провайдеру — обратитесь в поддержку |
| 429 | `RATE_LIMITED` | Превышен лимит запросов. В ответе приходит заголовок `Retry-After` с рекомендованной паузой |
| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при запуске виртуальной машины |
| 503 | `WAKE_TIMEOUT` | Блокирующий `?wait=true` не дождался готовности (таймаут ~6.5 минуты): машина так и не поднялась или туннель не подключился. Сервер возвращается в `sleeping` — повторный вызов безопасен |

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

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

- **Поведение при таймауте `?wait=true`.** Если за ~6.5 минуты виртуальная машина не поднялась, эндпоинт возвращает `503 WAKE_TIMEOUT` и пробует откатить сервер в `sleeping` — чтобы квота не висела на «вечно зависшем» сервере. Внутри этого окна платформа повторяет команду запуска, если облако её потеряло, поэтому таймаут означает, что машина действительно не поднялась, а не что команда не дошла. Поможет повторный `/wake` или [`/repair`](./repair.md).
- **Поля расширенной ошибки для AI-агентов.** При 402/403 тело ошибки дополнительно содержит `userMessage` (переведённая формулировка для пользователя), `alternatives` (список путей решения) и `hint` (совет AI-агенту, повторять автоматически или нет). Используйте эти поля в UI вместо голого `code`/`message`.
- **Пробуждение по обращению к субдомену срабатывает не на каждый запрос.** Оно запускается в четырёх случаях: у сервера [политика доступа](/docs/infra/access/access-policy) `PUBLIC`, посетитель авторизован, запрос пришёл с [токеном доступа](/docs/infra/access-tokens) режима `api-bearer`, получатель открыл ссылку режима `share-url`. Сервер с запретом на пробуждение не поднимется и в этих случаях — см. пункт ниже. Запрос без авторизации к серверу с любой другой политикой, включая `OWNER_ONLY` по умолчанию, оставляет сервер в статусе `sleeping`: обычный запрос получает страницу входа со статусом `200`, а API-клиент — запрос с заголовком `Accept: application/json`, `Authorization: Bearer` или `X-Requested-With: XMLHttpRequest`, а также любой запрос по пути `/api/` — получает `401 BH_LOGIN_REQUIRED`. На сервере с политикой `PUBLIC` запросы `GET` и `HEAD` от поисковых роботов и автоматических клиентов — например `curl`, `wget`, `python-requests`, `go-http-client`, `java/`, браузеры без интерфейса и запрос без заголовка `User-Agent` — машину не поднимают, чтобы обход роботом не держал её включённой. На таком сервере запросы `POST`, `PUT`, `PATCH` и `DELETE` будят её от любого клиента: это вызовы вебхуков и API, а не обход. Из скрипта и из консоли поднимайте сервер явным `/wake` с `wait=true` — тогда ответ придёт, когда сервер уже принимает запросы.
- **Сервер с флагом `preventWake` вызов `/wake` не поднимает** — коды отказа в таблице выше. Запрет ставит платформа при заморозке баланса, окончании пробного периода и административной блокировке, а сервер агента или бота получает его при любой остановке — из карточки или вызовом [`/sleep-now`](./sleep-now.md). Отдельный сервер поднимает [`/start`](./start.md): он снимает запрет, но заморозку баланса не обходит. У galaxy-приложения запрет на хосте блокирует и `/start` — см. [Galaxy-приложение](/docs/infra/galaxy).
- **Проверка доступности ДО вызова.** Перед `/wake` вызывайте [`GET /v1/me`](/docs/keys-auth) и смотрите `capabilities.servers.wake.available`. Если `false`, пользователю нужно совершить действие (пополнить баланс, обновить тариф) до того, как пробуждение станет возможным.
- **Публичный адрес машины после пробуждения другой.** Проснувшаяся машина получает адрес заново, поэтому поле `ip` в [`GET /v1/infra/servers/:id`](/docs/infra/servers/get) после каждого цикла сна отдаёт новое значение. Это относится ко всем тарифам, включая невытесняемые. То, что обращается к серверу по адресу — запись DNS, внешний мониторинг, — переводите на HTTPS-субдомен из поля `appUrl`: пробуждение его не меняет. Обратное направление так не лечится: когда внешний сервис пускает только по списку разрешённых IP, подставить в этот список нечего — постоянного исходящего адреса платформа не даёт ни в одной модели размещения, подробности в разделе [Исходящий IP](/docs/infra/galaxy#исходящий-ip).
- **Для `error`-сервера `/wake` не подходит** — используйте [`/start`](./start.md) или [`/repair`](./repair.md).

## Galaxy-приложения (`kind=GALAXY_APP`)

Параметр `?wait=true` на galaxy-приложении ожидания готовности не даёт: ответ приходит сразу, кода `WAKE_TIMEOUT` здесь не бывает. После холодного старта хоста приложение какое-то время остаётся в статусе `sleeping` — отслеживайте готовность опросом [`GET /v1/infra/servers/:id`](/docs/infra/servers/get).

Полная карта операций жизненного цикла приложения — [Galaxy-приложение](/docs/infra/galaxy).

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

- [Запустить сервер](./start.md)
- [Усыпить сейчас](./sleep-now.md)
- [Восстановить туннель](./repair.md)
- [Тариф и доступ](/docs/infra#тариф-и-доступ)