[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-infra\u002Flifecycle\u002Fwake":3,"docs-tabs-infra\u002Flifecycle\u002Fwake":6},{"content":4,"lastmod":5},"\n## Разбудить сервер\n\n`POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fwake`\n\nПробуждает сервер из `sleeping` или `provisioning`. В отличие от [`\u002Fstart`](.\u002Fstart.md), `\u002Fwake` поддерживает блокирующий режим через `?wait=true` — ответ возвращается только когда сервер полностью готов (виртуальная машина запущена **и** туннель подключился) или сработал таймаут. Используйте блокирующий режим, когда клиенту нужна готовность перед следующим шагом (cron-задача, триггерный вызов), и асинхронный — когда можно подождать на опросе.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | По умолч. | Описание |\n|----------|---|-----|:-----:|-----------|----------|\n| `id` | path | string (UUID) | да | — | ID сервера в статусе `sleeping` или `provisioning` |\n| `wait` | query | string | нет | — | `true` — блокирующий режим: ответ вернётся только когда сервер готов (до 6.5 минут) или сработает таймаут. Любое другое значение — асинхронный режим, ответ сразу |\n\nТело запроса пустое.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\n# Асинхронный вызов — ответ сразу, готовность проверяйте опросом\ncurl -X POST -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fwake\n\n# Блокирующий — ждёт готовности до ~6.5 минут\ncurl -X POST -H \"X-Api-Key: YOUR_API_KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fwake?wait=true\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fwake?wait=true\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\n\u002F\u002F Блокирующий вариант — проще всего для последующих шагов\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fwake?wait=true`,\n  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }\n)\nconst body = await res.json()\nif (!body.success) {\n  \u002F\u002F Rich-error: показать пользователю userMessage, предложить alternatives\n  console.error(body.error.userMessage ?? body.error.message)\n  if (body.error.alternatives) console.log('Варианты:', body.error.alternatives)\n  throw new Error(body.error.code)\n}\nconsole.log(`Сервер готов: ${body.data.appUrl}`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fwake?wait=true`,\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | `true` при успешном пробуждении |\n| `data.id` | string (UUID) | ID сервера |\n| `data.status` | string | Актуальный статус (`RUNNING` при `wait=true` успехе, `PROVISIONING` в асинхронном режиме) |\n| `data.blackholeStatus` | string | Состояние туннеля (`CONNECTED` в блокирующем при успехе) |\n| `data.appUrl` | string \\| null | HTTPS-адрес приложения |\n\n## Пример ответа\n\nУспешное пробуждение (`?wait=true`):\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"e765edfc-ba0a-43de-b8ea-838dd872c522\",\n    \"status\": \"RUNNING\",\n    \"blackholeStatus\": \"CONNECTED\",\n    \"appUrl\": \"https:\u002F\u002Fapp-05b67cf7.vibecode.bitrix24.tech\"\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n402 — коммерческий тариф обязателен (расширенный формат ошибки для AI-агентов):\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"COMMERCIAL_PLAN_REQUIRED\",\n    \"message\": \"Waking this server requires a commercial Bitrix24 plan or an active trial\",\n    \"userMessage\": \"Для пробуждения сервера нужен коммерческий тариф Битрикс24 или активный trial. Оформите тариф на https:\u002F\u002Fwww.bitrix24.ru\u002Fprices\u002F\",\n    \"alternatives\": [\n      \"Обновить тариф Битрикс24 и повторить\",\n      \"Перейти на AI Router с BYOK-ключами — он работает на любом тарифе\"\n    ],\n    \"hint\": \"Не повторяйте автоматически — нужно действие пользователя\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 402 | `COMMERCIAL_PLAN_REQUIRED` | Бесплатный тариф и trial недоступен — обновите тариф Битрикс24 |\n| 402 | `TRIAL_EXPIRED` | Trial использован и завершился |\n| 402 | `BILLING_EXHAUSTED` | Баланс Вайбкод исчерпан — пополните |\n| 402 | `ACCOUNT_FROZEN` | Баланс заморожен |\n| 403 | `SERVER_WAKE_BLOCKED` | Пробуждение заблокировано не из-за биллинга (завершённый trial, административный блок, нарушения безопасности) |\n| 404 | `NOT_FOUND` | Сервер не в статусе `sleeping`\u002F`provisioning`, удалён или принадлежит другому API-ключу |\n| 422 | `VM_MISSING` | У записи нет `externalId` — виртуальная машина не создана у провайдера. Удалите сервер и создайте новый |\n| 429 | `RATE_LIMITED` | Превышен лимит запросов. В ответе приходит заголовок `Retry-After` с рекомендованной паузой |\n| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при запуске виртуальной машины |\n| 503 | `WAKE_TIMEOUT` | Блокирующий `?wait=true` не дождался готовности (таймаут ~6.5 минуты). Сервер возвращается в `sleeping` — попробуйте снова |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Поведение при таймауте `?wait=true`.** Если за ~6.5 минуты виртуальная машина не поднялась, эндпоинт возвращает `503 WAKE_TIMEOUT` и пробует откатить сервер в `sleeping` — чтобы квота не висела на «вечно зависшем» сервере. Поможет повторный `\u002Fwake` или [`\u002Frepair`](.\u002Frepair.md).\n- **Поля расширенной ошибки для AI-агентов.** При 402\u002F403 тело ошибки дополнительно содержит `userMessage` (переведённая формулировка для пользователя), `alternatives` (список путей решения) и `hint` (совет AI-агенту, повторять автоматически или нет). Используйте эти поля в UI вместо голого `code`\u002F`message`.\n- **`\u002Fwake` не нужен при доступе через HTTPS-субдомен.** Любое обращение к HTTPS-субдомену сервера само инициирует пробуждение BLACKHOLE-сервера. Явный `\u002Fwake` нужен, когда:\n  - Клиенту нужен программный gate «сначала разбуди, потом делай» — через `wait=true`.\n  - Сервер помечен `preventWake=true` (биллинговая блокировка, требует ручного действия).\n- **Проверка доступности ДО вызова.** Перед `\u002Fwake` вызывайте [`GET \u002Fv1\u002Fme`](\u002Fdocs\u002Fkeys-auth) и смотрите `capabilities.servers.wake.available`. Если `false`, пользователю нужно совершить действие (пополнить баланс, обновить тариф) до того, как пробуждение станет возможным.\n- **Для `error`-сервера `\u002Fwake` не подходит** — используйте [`\u002Fstart`](.\u002Fstart.md) или [`\u002Frepair`](.\u002Frepair.md).\n\n## Смотрите также\n\n- [Запустить сервер](.\u002Fstart.md) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fstart` — ручной старт без блокировки.\n- [Усыпить сейчас](.\u002Fsleep-now.md) — обратная операция.\n- [Восстановить туннель](.\u002Frepair.md) — если сервер проснулся, но туннель не подключается.\n- [Тариф и доступ](\u002Fdocs\u002Finfra#тариф-и-доступ) — контекст для 402-ошибок.\n","2026-06-29",{"start.md":7},"\n## Запустить сервер\n\n`POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fstart`\n\nПоднимает сервер из состояний `sleeping`, `error` или `provisioning`. Для `sleeping` виртуальная машина снова запускается у провайдера и возвращается к статусу `running` по мере готовности — вызов возвращает ответ сразу, не дожидаясь фактической готовности. Её нужно отслеживать опросом [`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id`](\u002Fdocs\u002Finfra\u002Fservers\u002Fget). Для `error` с подключённым туннелем (`blackholeStatus: \"CONNECTED\"`) сервер сразу переводится в `running` без обращения к провайдеру. Для `provisioning` делается повторная попытка старта без сброса таймера ожидания. Для `running` сервера вызов возвращает 404.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID сервера |\n\nТело запроса пустое.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fstart\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fstart\n```\n\n### JavaScript — личный ключ\n\n```javascript\nawait fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fstart`,\n  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }\n)\n\u002F\u002F Ждать готовности — опрашивать GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nawait fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fstart`,\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | `true`. Виртуальная машина запущена у провайдера или команда на запуск отправлена в фоновом режиме |\n\n## Пример ответа\n\n```json\n{ \"success\": true }\n```\n\n## Пример ответа при ошибке\n\n404 — сервер в статусе `running`\u002F`deleted` либо чужой:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"NOT_FOUND\",\n    \"message\": \"Sleeping, error, or provisioning server not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 402 | `ACCOUNT_FROZEN` | Баланс Вайбкод заморожен. Пополните и повторите |\n| 404 | `NOT_FOUND` | Сервер в статусе `running`\u002F`deleted` либо принадлежит другому API-ключу |\n| 409 | `CONFLICT` | Статус сервера изменился во время операции — повторите запрос |\n| 422 | `VM_MISSING` | У записи нет `externalId` — виртуальная машина не создана или удалена извне. Удалите сервер и создайте новый |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при запуске виртуальной машины |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Блокирующий вариант.** Если клиенту нужна полная готовность сервера перед следующим шагом — используйте [`POST \u002Fwake?wait=true`](.\u002Fwake.md) вместо `\u002Fstart`. Он ждёт `status: \"running\"` + `blackholeStatus: \"CONNECTED\"` до ~6.5 минут.\n- **Ручной `\u002Fstart` обходит `preventWake`.** В отличие от автоматического пробуждения при обращении к субдомену, явный `POST \u002Fstart` снимает флаг `preventWake` и запускает сервер даже если он был заблокирован. Биллинговые блокировки (`ACCOUNT_FROZEN`) обходятся отдельным пополнением, не через `\u002Fstart`.\n- **Для `running` возвращает 404, не 409.** Сознательный выбор: сервер уже в нужном состоянии, делать нечего. Для перезагрузки — [`POST \u002Freboot`](.\u002Freboot.md).\n\n## Смотрите также\n\n- [Остановить сервер](.\u002Fstop.md) — `POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fstop`.\n- [Разбудить сервер (с `?wait=true`)](.\u002Fwake.md) — блокирующий вариант с ожиданием готовности.\n- [Немедленно усыпить](.\u002Fsleep-now.md) — обратная операция.\n- [Обновить статус](.\u002Frefresh.md) — принудительно опросить провайдера после старта.\n- [Получить сервер](\u002Fdocs\u002Finfra\u002Fservers\u002Fget) — опрос готовности.\n"]