## Запустить сервер

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

Поднимает сервер из состояний `sleeping`, `error` или `provisioning`. Для `sleeping` виртуальная машина снова запускается у провайдера и возвращается к статусу `running` по мере готовности — вызов возвращает ответ сразу, не дожидаясь фактической готовности. Её нужно отслеживать опросом [`GET /v1/infra/servers/:id`](/docs/infra/servers/get). Для `error` с подключённым туннелем (`blackholeStatus: "CONNECTED"`) сервер сразу переводится в `running` без обращения к провайдеру. Для `provisioning` делается повторная попытка старта без сброса таймера ожидания. Если сервер не в одном из этих состояний — например, уже `running` — вызов возвращает 422 `SERVER_WRONG_STATE` с текущим состоянием `currentState` и списком доступных действий `availableActions`.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `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/start
```

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

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

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/start`,
  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
// Ждать готовности — опрашивать GET /v1/infra/servers/:id
```

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

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

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true`. Виртуальная машина запущена у провайдера или команда на запуск отправлена в фоновом режиме |

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

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

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

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

```json
{
  "success": false,
  "error": {
    "code": "SERVER_WRONG_STATE",
    "message": "Server is RUNNING; /start requires one of SLEEPING, ERROR, PROVISIONING.",
    "userMessage": "Server is currently RUNNING. Start only applies to SLEEPING, ERROR, or PROVISIONING servers.",
    "currentState": { "status": "running", "blackholeStatus": "CONNECTED", "hasExternalId": true },
    "availableActions": ["reboot", "sleep-now", "delete"]
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 402 | `ACCOUNT_FROZEN` | Баланс Вайбкод заморожен. Пополните и повторите |
| 403 | `SERVER_WAKE_BLOCKED` | Galaxy-приложение: пробуждение хоста-галактики заблокировано. У отдельной виртуальной машины этого кода нет — там `/start` снимает запрет сам |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key) |
| 404 | `SERVER_NOT_FOUND` | Сервера с таким `id` нет — удалён или принадлежит другому API-ключу |
| 404 | `GALAXY_HOST_NOT_FOUND` | Galaxy-приложение: хост-галактика, на которой оно размещено, не найдена |
| 409 | `CONFLICT` | Статус сервера изменился во время операции — повторите запрос |
| 422 | `SERVER_WRONG_STATE` | Сервер существует, но не в статусе `sleeping`/`error`/`provisioning`. В `error.currentState` — текущее состояние, в `error.availableActions` — что можно сделать сейчас |
| 422 | `SERVER_WRONG_STATE` | Galaxy-приложение, код которого ни разу не загружали, либо приложение в статусе `error`: `/start` не восстанавливает упавшую сборку. В `error.message` — вызов загрузки кода, которым это лечится |
| 422 | `CREDENTIAL_MISSING` | Galaxy-приложение: у хоста-галактики нет привязанного доступа к облачному провайдеру — обратитесь в поддержку |
| 422 | `VM_MISSING` | У записи нет `externalId` — виртуальная машина не создана или удалена извне. Удалите сервер и создайте новый |
| 422 | `GUEST_NOT_BOOTING` | Гостевая операционная система машины не загружается — состояние терминальное, запуск бесполезен. Сервер нужно пересоздать, в `error.availableActions` остаётся только `delete` |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |
| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при запуске виртуальной машины |

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

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

- **Блокирующий вариант.** Если клиенту нужна полная готовность сервера перед следующим шагом — используйте [`POST /wake?wait=true`](./wake.md) вместо `/start`. Он ждёт `status: "running"` + `blackholeStatus: "CONNECTED"` до ~6.5 минут.
- **Ручной `/start` обходит `preventWake`.** В отличие от [автоматического пробуждения](./wake.md), которое срабатывает не на каждое обращение к субдомену, явный `POST /start` снимает флаг `preventWake` и запускает сервер даже если он был заблокирован. Биллинговые блокировки (`ACCOUNT_FROZEN`) обходятся отдельным пополнением, не через `/start`.
- **Для `running` возвращает 422 `SERVER_WRONG_STATE`.** Сервер уже запущен — повторного старта не требуется. Для перезагрузки — [`POST /reboot`](./reboot.md).
- **Два `422` на этом маршруте означают разное.** `SERVER_WRONG_STATE` — состояние временное, повтор осмыслен. `GUEST_NOT_BOOTING` — терминальное: обрабатывайте его как «пересоздать сервер», а не как временную ошибку, иначе запуск по расписанию будет повторяться вечно.

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

`/start` на спящем galaxy-приложении поднимает его через хост — так же, как [`/wake`](./wake.md). Одно отличие от отдельной виртуальной машины важно для клиента: флаг `preventWake` на хосте блокирует `/start`, и здесь запуск запрет **не** снимает.

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

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

- [Galaxy-приложение](/docs/infra/galaxy)
- [Остановить сервер](./stop.md)
- [Разбудить сервер (с `?wait=true`)](./wake.md)
- [Немедленно усыпить](./sleep-now.md)
- [Обновить статус](./refresh.md)
- [Получить сервер](/docs/infra/servers/get)