## Регионы провайдера

`GET /v1/infra/providers/:providerId/regions`

Возвращает список дата-центров (зон), в которых провайдер может размещать виртуальные машины. Значение `id` используется как параметр `region` при [создании сервера](/docs/infra/servers/create). По умолчанию выбирайте **первый элемент массива** — он является актуальной запасной зоной платформы с запасом свободных IP.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `providerId` | path | string | да | ID провайдера из [`GET /v1/infra/providers`](./list.md), например `bitrix-cloud` |

## Примеры

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

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/infra/providers/bitrix-cloud/regions
```

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

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/infra/providers/bitrix-cloud/regions
```

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

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/infra/providers/bitrix-cloud/regions',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data: regions } = await res.json()
const defaultRegion = regions[0].id  // актуальный фолбэк платформы
```

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

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/infra/providers/bitrix-cloud/regions',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив регионов |
| `data[].id` | string | ID региона, передаётся как `region` при создании сервера (например `ru-central1-b`) |
| `data[].name` | string | Название для отображения пользователю (например `"Москва (зона B)"`) |
| `data[].country` | string | Двухбуквенный код страны ISO 3166-1 (`RU`) |

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

```json
{
  "success": true,
  "data": [
    { "id": "ru-central1-b", "name": "Москва (зона B)", "country": "RU" },
    { "id": "ru-central1-a", "name": "Москва (зона A)", "country": "RU" },
    { "id": "ru-central1-d", "name": "Москва (зона D)", "country": "RU" },
    { "id": "ru-central1-e", "name": "Москва (зона E)", "country": "RU" }
  ]
}
```

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

404 — неизвестный `providerId`:

```json
{
  "success": false,
  "error": {
    "code": "NO_CREDENTIALS",
    "message": "No credentials configured for provider nonexistent"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 404 | `NO_CREDENTIALS` | Провайдер с таким `providerId` не сконфигурирован на платформе |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

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

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

- **Переключение на запасную зону при исчерпании IP-адресов.** Если в запрошенной зоне у провайдера кончились свободные IP, при создании сервера платформа автоматически пробует следующие зоны массива в порядке их появления и в ответе создания проставляет `region`, куда сервер реально попал. Факт переключения на запасную зону фиксируется в аудит-логе событием `SERVER_ZONE_FALLBACK` с исходной и реальной зонами.
- Ответ не пагинируется.

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

- [Список провайдеров](./list.md)
- [Тарифы провайдера](./plans.md)
- [Образы ОС провайдера](./images.md)
- [Создание сервера](/docs/infra/servers/create)