API Tihost - документация: ключ, эндпоинты, лимиты и ошибки

Q: Куда писать, если ответ выглядит неправильно?

На почту технической поддержки tech-support@tihost.io, приложив request_id из тела ответа - по нему мы найдём конкретный вызов. Форма заявок в панели вопросы по API не обрабатывает

Быстрый старт

Выпустите ключВыпустите ключ в разделе API панели или в боте
Подставьте его в заголовокПередайте его в заголовке Authorization
Сделайте первый запросПроверьте связь методом /ping

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/ping"

Если всё верно, придёт такой ответ:

Ответ · 200

{
  "status": "ok",
  "account_id": 1042,
  "server_time": "2026-08-11T12:30:00Z"
}

Авторизация

Все запросы требуют ключ в заголовке. Ключ действует бессрочно, пока вы его не перевыпустите или не удалите

Заголовок	Тип	Обязателен	Значения	Описание
`Authorization`	string	да	`Bearer <token>`	Ключ доступа. Схема Bearer, регистр схемы не важен
`Idempotency-Key`	string	нет	`1…128`	Ключ повтора для пишущих методов. Любая строка до 128 символов, обычно uuid

Значение ключа показывается один раз при выпуске - на сервере хранится только его хеш
Ключ даёт доступ ко всему аккаунту, поэтому не кладите его в клиентский код и публичные репозитории
Перевыпуск отключает старый ключ мгновенно

Лимиты

Лимит считается на ключ и раздельно по назначению: 60 запросов в минуту на чтение и 10 в минуту на методы, меняющие состояние. Окна независимы - поток чтения не блокирует управление. Заголовки лимита приходят с каждым ответом, а не только при отказе

Заголовок	Тип	Значения	Описание
`X-RateLimit-Limit`	integer	`60 · 10`	Порог окна: 60 для чтения, 10 для методов, меняющих состояние
`X-RateLimit-Remaining`	integer	`0…60 · 0…10`	Сколько запросов осталось в текущем окне
`X-RateLimit-Reset`	integer	-	Unix-время начала следующего окна
`Retry-After`	integer	`1…61`	Через сколько секунд повторить. Только при 429
`X-Request-Id`	string	-	Идентификатор вызова. Приходит с каждым ответом
`Idempotent-Replay`	string	`true`	Есть только на ответе-повторе: операция НЕ выполнялась заново

Повторы

Пишущие методы принимают заголовок Idempotency-Key. Повтор с тем же ключом вернёт сохранённый ответ и НЕ выполнит операцию заново

Ключ нужен там, где повтор опасен: покупка и продление списывают деньги, и обычный ретрай после таймаута купит второй сервер или спишет за продление дважды
Ключ живёт сутки и уникален в пределах вашего ключа доступа. Обычно это uuid, сгенерированный перед вызовом
Повторный ответ помечен заголовком Idempotent-Replay: true. Тот же ключ с ДРУГИМ телом - ошибка idempotency_key_reused

Методы

Ответ всегда объект: в него можно добавить поле, не сломав ваш код. Метки у методов говорят, что метод делает с аккаунтом - читает, меняет машину или тратит деньги

Показать:

GET/ping

Проверка ключа и связи. Возвращает идентификатор аккаунта и время сервера

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`status`	string	да	`ok`	Всегда ok, если ключ действителен
`account_id`	integer	да	-	Идентификатор аккаунта, которому принадлежит ключ
`server_time`	datetime	да	-	Текущее время сервера в UTC, ISO 8601

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/ping"

Ответ · 200

{
  "status": "ok",
  "account_id": 1042,
  "server_time": "2026-08-11T12:30:00Z"
}

GET/balance

Сколько денег на аккаунте. Спросите перед покупкой и продлением - отказ по балансу приходит уже 402-й ошибкой

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`balance_usd`	string	да	-	Баланс. Строкой, чтобы не терять копейки
`currency`	string	да	`USD`	Валюта баланса. Сейчас всегда USD

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/balance"

Ответ · 200

{
  "balance_usd": "12.50",
  "currency": "USD"
}

GET/catalog/plans

Конфигурации, доступные к оформлению в этой локации, с ценой за каждый срок. Идентификаторы отсюда идут в POST /servers

Параметры запроса (query)

Параметр	Тип	Обязателен	Значения	Описание
`location`	string	да	`germany · finland · poland`	Код локации. Цены и список образов зависят от неё

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`location`	string	да	`germany · finland · poland`	Локация, к которой относятся цены в ответе
`items`	array<object>	да	-	Конфигурации. Пусто - в этой локации сейчас нечего оформить
`id`	integer	да	-	Идентификатор конфигурации для POST /servers
`cpu`	integer	да	-	Ядер vCPU
`ram_mb`	integer	да	-	Оперативная память, МиБ (4096 = 4 ГиБ)
`disk_gb`	integer \| null	да, но может быть null	-	Диск, ГБ
`periods`	array<object>	да	-	Сроки оплаты и итог к списанию за каждый
`months`	integer	да	`1 · 3 · 6 · 12`	Срок в месяцах
`total_usd`	string	да	-	Сколько спишется за весь срок. Строкой
`discount_percent`	integer	да	`0 · 10 · 15 · 20`	Скидка за длительный срок, %

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/catalog/plans?location=germany"

Ответ · 200

{
  "location": "germany",
  "items": [
    {
      "id": 41,
      "cpu": 2,
      "ram_mb": 4096,
      "disk_gb": 60,
      "periods": [
        { "months": 1, "total_usd": "4.00", "discount_percent": 0 },
        { "months": 3, "total_usd": "10.80", "discount_percent": 10 },
        { "months": 6, "total_usd": "20.40", "discount_percent": 15 },
        { "months": 12, "total_usd": "38.40", "discount_percent": 20 }
      ]
    }
  ]
}

GET/catalog/os

Образы, совместимые с выбранной конфигурацией. Идентификатор отсюда идёт в POST /servers

Параметры запроса (query)

Параметр	Тип	Обязателен	Значения	Описание
`location`	string	да	`germany · finland · poland`	Код локации. Цены и список образов зависят от неё
`plan_id`	integer	да	`> 0`	Идентификатор конфигурации из GET /catalog/plans

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`items`	array<object>	да	-	Доступные образы
`id`	integer	да	-	Идентификатор образа для POST /servers
`name`	string	да	-	Название образа

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/catalog/os?location=germany&plan_id=41"

Ответ · 200

{
  "items": [
    { "id": 101, "name": "Ubuntu 24.04" },
    { "id": 102, "name": "Debian 12" }
  ]
}

POST/serversменяет состояниеДеньги

Купить сервер. Списывает деньги с баланса и создаёт машину. IP и состояние появятся не сразу - читайте их через GET /servers/{id}

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`location`	string	да	`germany · finland · poland`	Код локации. Цены и список образов зависят от неё
`plan_id`	integer	да	`> 0`	Идентификатор конфигурации из GET /catalog/plans
`os_id`	integer	да	`> 0`	Идентификатор образа из GET /catalog/os
`months`	integer	да	`1 · 3 · 6 · 12`	Срок оплаты. Чем длиннее, тем больше скидка - точные суммы в GET /catalog/plans
`name`	string \| null	нет	`2…49`	Имя машины. Латиница, цифры, пробелы и дефис; пробелы станут дефисами, регистр опустится. Пусто - назначим сами (my-server-N)

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`id`	integer	да	-	Идентификатор сервера. С ним работают остальные методы
`name`	string	да	-	Имя после нормализации - может отличаться от присланного
`os`	string \| null	да, но может быть null	-	Операционная система
`location`	string	да	`germany · finland · poland`	Код локации. null - локация не определена
`login`	string \| null	да, но может быть null	`root · Administrator`	Учётная запись машины
`password`	string \| null	да, но может быть null	-	Пароль. Показывается ОДИН раз - сохраните его
`rent_expires_at`	datetime	да	-	Когда истекает оплаченный срок, UTC
`charged_usd`	string	да	-	Сколько списано. Строкой, чтобы не терять копейки
`balance_usd`	string	да	-	Остаток баланса. Строкой

Запрос · cURL

curl -X POST "https://api-public.tihost.io/v1/servers" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"location": "germany", "plan_id": 41, "os_id": 101, "months": 3}'

Ответ · 201

{
  "id": 2427,
  "name": "my-server-1",
  "os": "Ubuntu 24.04",
  "location": "germany",
  "login": "root",
  "password": "8Fk2mQx7ZpLr",
  "rent_expires_at": "2026-11-10T10:00:00Z",
  "charged_usd": "10.80",
  "balance_usd": "11.50"
}

GET/servers

Список серверов аккаунта. Пагинации нет - серверов у аккаунта единицы

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`items`	array<object>	да	-	Массив серверов. Пустой, если серверов нет
`id`	integer	да	-	Идентификатор сервера. Тот же, что в адресе панели
`name`	string \| null	да, но может быть null	-	Имя машины
`os`	string \| null	да, но может быть null	-	Операционная система
`ip`	string \| null	да, но может быть null	-	IPv4-адрес
`state`	string \| null	да, но может быть null	`active · running · stopped · creating · installing · restarting · error · null`	Состояние машины. Список неполон - значение приходит от панели как есть. null - состояние неизвестно
`location`	string \| null	да, но может быть null	`germany · finland · poland`	Код локации. null - локация не определена
`rent_expires_at`	datetime \| null	да, но может быть null	-	Когда истекает аренда, UTC
`auto_renew`	boolean	да	`true · false`	Включено ли автопродление
`total`	integer	да	-	Сколько серверов в ответе

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/servers"

Ответ · 200

{
  "items": [
    {
      "id": 2427,
      "name": "web-01",
      "os": "Ubuntu 24.04",
      "ip": "141.95.41.91",
      "state": "active",
      "location": "germany",
      "rent_expires_at": "2026-09-01T10:00:00Z",
      "auto_renew": true
    }
  ],
  "total": 1
}

GET/servers/{id}

Данные одного сервера. Состояние спрашивается у панели виртуализации; если она не ответила, приходит наш снимок с data_source: cached

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`id`	integer	да	-	Идентификатор сервера. Тот же, что в адресе панели
`name`	string \| null	да, но может быть null	-	Имя машины
`os`	string \| null	да, но может быть null	-	Операционная система
`ip`	string \| null	да, но может быть null	-	IPv4-адрес
`state`	string \| null	да, но может быть null	`active · running · stopped · creating · installing · restarting · error · null`	Состояние машины. Список неполон - значение приходит от панели как есть. null - состояние неизвестно
`location`	string \| null	да, но может быть null	`germany · finland · poland`	Код локации. null - локация не определена
`rent_expires_at`	datetime \| null	да, но может быть null	-	Когда истекает аренда, UTC
`auto_renew`	boolean	да	`true · false`	Включено ли автопродление
`resources`	object	да	-	Конфигурация машины
`cpu`	integer \| null	да, но может быть null	-	Ядер vCPU
`ram_mb`	integer \| null	да, но может быть null	-	Оперативная память, МиБ (4096 = 4 ГиБ)
`disk_gb`	integer \| null	да, но может быть null	-	Диск, ГБ
`created_at`	datetime \| null	да, но может быть null	-	Когда сервер создан, UTC
`data_source`	string	да	`live · cached`	live - данные от панели виртуализации, cached - наш снимок (панель не ответила)
`renew_prices`	array<object>	да	-	Стоимость продления по срокам. Считается тем же кодом, что и списание, и учитывает индивидуальную цену сервера. Пусто - цену определить не удалось
`days`	integer	да	`2 · 7 · 30 · 90 · 180 · 365`	Срок продления в днях - его же принимает POST /servers/{id}/renew
`total_usd`	string	да	-	Сумма к списанию за срок. Строка, чтобы не терять центы

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/servers/2427"

Ответ · 200

{
  "id": 2427,
  "name": "web-01",
  "os": "Ubuntu 24.04",
  "ip": "141.95.41.91",
  "state": "active",
  "location": "germany",
  "rent_expires_at": "2026-09-01T10:00:00Z",
  "auto_renew": true,
  "resources": {
    "cpu": 2,
    "ram_mb": 4096,
    "disk_gb": 60
  },
  "created_at": "2026-05-02T09:12:00Z",
  "data_source": "live",
  "renew_prices": [
    { "days": 2, "total_usd": "0.27" },
    { "days": 7, "total_usd": "0.93" },
    { "days": 30, "total_usd": "4.00" },
    { "days": 90, "total_usd": "10.80" },
    { "days": 180, "total_usd": "20.40" },
    { "days": 365, "total_usd": "38.40" }
  ]
}

POST/servers/{id}/renewменяет состояниеДеньги

Продлить аренду сервера. Списывает деньги с баланса аккаунта

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`days`	integer	да	`2 · 7 · 30 · 90 · 180 · 365`	Срок продления. Другие значения не принимаются

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`rent_expires_at`	datetime	да	-	Новый срок аренды, UTC
`charged_usd`	string	да	-	Сколько списано. Строкой, чтобы не терять копейки
`balance_usd`	string	да	-	Остаток баланса. Строкой

Запрос · cURL

curl -X POST "https://api-public.tihost.io/v1/servers/2427/renew" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"days": 30}'

Ответ · 200

{
  "rent_expires_at": "2026-10-01T10:00:00Z",
  "charged_usd": "4.00",
  "balance_usd": "11.50"
}

PATCH/servers/{id}/auto-renewменяет состояние

Включить или выключить автопродление этого сервера

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`enabled`	boolean	да	`true · false`	Включить автопродление

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`auto_renew`	boolean	да	`true · false`	Включено ли автопродление

Запрос · cURL

curl -X PATCH "https://api-public.tihost.io/v1/servers/2427/auto-renew" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"enabled": true}'

Ответ · 200

{
  "auto_renew": true
}

POST/servers/{id}/powerменяет состояние

Включить, выключить или перезапустить машину. Панель выполняет команду асинхронно: ответ говорит, в какое состояние машина переходит

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`action`	string	да	`start · stop · restart`	Что сделать с машиной

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`ok`	boolean	да	`true`	Признак выполнения
`expected_state`	string	да	`running · stopped · restarting`	Состояние, в которое переходит машина. Фактическое читайте через GET /servers/{id}

Запрос · cURL

curl -X POST "https://api-public.tihost.io/v1/servers/2427/power" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"action": "restart"}'

Ответ · 200

{
  "ok": true,
  "expected_state": "restarting"
}

PATCH/servers/{id}/nameменяет состояние

Сменить отображаемое имя машины

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`name`	string	да	`2…49`	Новое имя. Латиница, цифры, пробелы и дефис; пробелы станут дефисами, регистр опустится, остальное даст ошибку

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`name`	string	да	-	Имя после нормализации - может отличаться от присланного

Запрос · cURL

curl -X PATCH "https://api-public.tihost.io/v1/servers/2427/name" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "web-02"}'

Ответ · 200

{
  "name": "web-02"
}

POST/servers/{id}/passwordменяет состояние

Сменить пароль root/Administrator. Пусто в теле - сгенерируем сами

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`password`	string \| null	нет	`8…255 ASCII`	Новый пароль. Печатные ASCII без пробелов. null или отсутствует - сгенерируем сами

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`login`	string	да	`root · Administrator`	Учётная запись машины
`password`	string	да	-	Пароль. Показывается ОДИН раз - сохраните его

Запрос · cURL

curl -X POST "https://api-public.tihost.io/v1/servers/2427/password" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"password": null}'

Ответ · 200

{
  "login": "root",
  "password": "8Fk2mQx7ZpLr"
}

GET/servers/{id}/os

Образы, которые можно поставить на эту машину. Список зависит от её конфигурации и локации

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`items`	array<object>	да	-	Доступные образы
`id`	integer	да	-	Идентификатор образа для reinstall
`name`	string	да	-	Название образа

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/servers/2427/os"

Ответ · 200

{
  "items": [
    { "id": 101, "name": "Ubuntu 24.04" },
    { "id": 102, "name": "Debian 12" }
  ]
}

POST/servers/{id}/reinstallменяет состояние

Переустановить ОС. Стирает диск безвозвратно, поэтому требует confirm: true

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`os_id`	integer	да	`> 0`	Идентификатор образа из GET /servers/{id}/os
`confirm`	boolean	да	`true`	Подтверждение. Только true - операция стирает все данные

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`ok`	boolean	да	`true`	Признак выполнения
`os`	string	да	-	Название образа
`login`	string	да	`root · Administrator`	Учётная запись машины
`password`	string	да	-	Пароль. Показывается ОДИН раз - сохраните его

Запрос · cURL

curl -X POST "https://api-public.tihost.io/v1/servers/2427/reinstall" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"os_id": 101, "confirm": true}'

Ответ · 200

{
  "ok": true,
  "os": "Ubuntu 24.04",
  "login": "root",
  "password": "8Fk2mQx7ZpLr"
}

GET/servers/{id}/scripts

Скрипты, разрешённые для ОС этой машины

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`items`	array<object>	да	-	Доступные скрипты
`id`	integer	да	-	Идентификатор скрипта для запуска
`name`	string	да	-	Название скрипта
`description`	string \| null	да, но может быть null	-	Что делает скрипт

Запрос · cURL

curl -H "Authorization: Bearer $TIHOST_TOKEN" \
  "https://api-public.tihost.io/v1/servers/2427/scripts"

Ответ · 200

{
  "items": [
    { "id": 12, "name": "Docker", "description": "Docker + docker compose" }
  ]
}

POST/servers/{id}/scripts/runменяет состояние

Запустить скрипт из списка выше

Параметры пути

Параметр	Тип	Обязателен	Значения	Описание
`id`	integer	да	`> 0`	Идентификатор сервера из списка или из адреса панели

Тело запроса (JSON)

Параметр	Тип	Обязателен	Значения	Описание
`script_id`	integer	да	`> 0`	Идентификатор скрипта из GET /servers/{id}/scripts

Поля ответа

Поле	Тип	Всегда есть	Значения	Описание
`ok`	boolean	да	`true`	Признак выполнения
`script_id`	integer	да	-	Идентификатор скрипта для запуска

Запрос · cURL

curl -X POST "https://api-public.tihost.io/v1/servers/2427/scripts/run" \
  -H "Authorization: Bearer $TIHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"script_id": 12}'

Ответ · 200

{
  "ok": true,
  "script_id": 12
}

Ошибки

Любая ошибка приходит в одном конверте. Завязывайтесь на поле code - оно машинное и стабильное, message может меняться

HTTP 429

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 60 read requests per 60 seconds",
    "details": {
      "limit": 60,
      "scope": "read",
      "retry_after": 27
    },
    "request_id": "9f4c1d0e8b7a4c2f9e1d3b6a8c5f2e7d"
  }
}

Поля конверта

Поле	Тип	Всегда есть	Значения	Описание
`error`	object	да	-	Единственный ключ верхнего уровня при ошибке. Успешные ответы его не содержат
`code`	string	да	-	Машинный код ошибки. Стабилен - завязывайтесь на него
`message`	string	да	-	Человекочитаемое описание. Может меняться, логику на нём не строить
`details`	object \| absent	не всегда	-	Машинные подробности. Есть не у всех ошибок
`limit`	integer	да	-	Порог лимита. Только у rate_limited
`retry_after`	integer	да	-	Через сколько секунд повторить. Только у rate_limited
`scope`	string	да	`read · write`	Назначение лимита, в котором отказано. Только у rate_limited
`missing_usd`	string	да	-	Сколько не хватает на балансе. Строка. Только у insufficient_funds
`refunded`	boolean	да	`true · false`	Вернулись ли деньги на баланс. Приходит у отказов покупки, когда списание уже прошло
`state`	string	да	-	Состояние машины, из-за которого действие невозможно. У conflict и server_busy
`available_actions`	array<string>	да	-	Какие действия сейчас доступны. У conflict на управлении питанием
`plan_id`	integer	да	-	Конфигурация, к которой относится отказ
`allowed`	array<string>	да	-	Допустимые значения параметра. Например список кодов локаций
`fields`	array<object>	да	-	Список полей, не прошедших валидацию. Только у invalid_request
`field`	string	да	-	Путь до поля, например query.location или body.months
`reason`	string	да	-	Чем именно поле не подошло
`request_id`	string	да	-	Идентификатор вызова. Совпадает с заголовком X-Request-Id

Коды ошибок

code	HTTP	Описание
`invalid_request`	400	Запрос не прошёл валидацию - смотрите details.fields
`unauthorized`	401	Заголовка Authorization нет или он не в схеме Bearer
`token_invalid`	401	Ключ не найден или отозван
`forbidden`	403	Доступ к объекту запрещён
`account_banned`	403	Аккаунт заблокирован
`insufficient_funds`	402	Не хватает денег на балансе - смотрите details.missing_usd
`not_found`	404	Объекта нет или он принадлежит другому аккаунту
`method_not_allowed`	405	Метод не поддерживается этим путём
`conflict`	409	Действие невозможно в текущем состоянии - смотрите details.state
`server_busy`	409	Машина занята другой операцией (создаётся, ставится ОС)
`rent_expired`	409	Аренда истекла - управление недоступно, продлите сервер
`server_no_ip`	409	У сервера нет IP-адреса - управление недоступно до его возврата, напишите в поддержку. Продление работает
`request_in_progress`	409	Идентичный запрос ещё выполняется
`idempotency_key_reused`	422	Тем же Idempotency-Key прислали ДРУГОЙ запрос
`rate_limited`	429	Превышен лимит запросов - повторите через Retry-After секунд
`internal_error`	500	Ошибка на нашей стороне. Присылайте request_id в поддержку
`service_unavailable`	503	Сервис временно недоступен

Поле request_id совпадает с заголовком X-Request-Id. Присылайте его в поддержку - по нему находится конкретный вызов

Вопросы

Где взять ключ?

В панели: раздел API - кнопка «Выпустить ключ». То же самое можно сделать в Telegram-боте: Профиль - API-ключ

Я потерял ключ, как посмотреть его снова?

Никак: на сервере хранится только хеш ключа. Нажмите «Перевыпустить» - старый ключ сразу перестанет работать, новый покажется один раз

Можно ли через API купить или продлить сервер?

Да. Покупка - POST /servers, продление - POST /servers/{id}/renew. Оба списывают деньги с баланса, поэтому шлите с ними Idempotency-Key: без него повтор после таймаута купит второй сервер

Что будет, если превысить лимит?

Придёт 429 с кодом rate_limited и заголовком Retry-After. Подождите указанное число секунд и повторите

Как вы будете менять API?

Версия зашита в адрес (/v1). В рамках версии мы можем добавлять поля, но не переименовывать и не удалять существующие

Куда писать, если ответ выглядит неправильно?

На почту технической поддержки [email protected], приложив request_id из тела ответа - по нему мы найдём конкретный вызов. Форма заявок в панели вопросы по API не обрабатывает

Словарь

API: Интерфейс, по которому программа получает данные вместо человека
endpoint: Конкретный адрес метода, например /servers. Полный адрес = база + путь
token: Ключ доступа. Строка, которая доказывает, что запрос от вас
header: Служебная строка запроса. Ключ передаётся в заголовке Authorization
JSON: Текстовый формат данных. Его понимают все языки программирования
HTTP 200 / 4xx / 5xx: Код ответа: 200 - успех, 4xx - ошибка на стороне запроса, 5xx - на нашей стороне
rate limit: Ограничение частоты: сколько запросов в минуту можно сделать одним ключом

Поддержка

Вопросы по API - на почту технической поддержки: [email protected]