Для AI-агентов: markdown этой страницы — /docs-content/applications/replace-server.md индекс документации — /llms.txt
Заменить сервер приложения
POST /v1/applications/:id/replace-server
Переносит приложение на другой сервер: на существующий сервер владельца или на новый, который метод создаёт сам. Старый сервер не удаляется. Приложение отвязывается от него, а сервер остаётся у владельца. Перед вызовом узнайте, возможна ли замена, и выберите сервер через GET /v1/applications/:id/available-servers.
Метод доступен только владельцу карточки и только его ключам. Администратор портала, который приложением не владеет, заменяет сервер в кабинете.
Авторизация: X-Api-Key со скоупом vibe:infra.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Параметрid (path) |
Типstring | Обяз.да | ОписаниеИдентификатор приложения. Список: GET /v1/applications |
ПараметрIdempotency-Key (header) |
Типstring | Обяз.нет | ОписаниеТолько для формы new, в форме { serverId } игнорируется. От 1 до 255 символов из A-Z, a-z, 0-9, _, ., :, -, пробелы по краям отбрасываются. Ключ действует в пределах API-ключа вызова. Как работает повтор — в «Известных особенностях» |
Поля запроса (body)
Тело принимает одну из двух форм. Поля из разных форм смешивать нельзя, лишние поля дают 400 VALIDATION_ERROR.
Свой существующий сервер.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
ПолеserverId |
Типstring | Обяз.да | ОписаниеИдентификатор сервера из servers[].id метода GET /v1/applications/:id/available-servers |
Новый сервер.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
Полеprovider |
Типstring | Обяз.да | ОписаниеИдентификатор провайдера, как в POST /v1/infra/servers |
Полеplan |
Типstring | Обяз.да | ОписаниеИдентификатор тарифа провайдера, как в POST /v1/infra/servers |
Полеregion |
Типstring | Обяз.нет | ОписаниеИдентификатор региона провайдера |
Примеры
curl — личный ключ
curl -X POST \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"serverId": "srv_new"}' \
https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server
curl — OAuth-приложение
curl -X POST \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"serverId": "srv_new"}' \
https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server
JavaScript — личный ключ
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/replace-server`, {
method: 'POST',
headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()
for (const warning of data.warnings) {
console.warn('Нужно доделать вручную:', warning)
}
JavaScript — OAuth-приложение
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/replace-server`, {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()
Новый сервер создаётся телом {"provider": "bitrix-cloud", "plan": "bc-small", "region": "ru-central1-b"}. Такой вызов платный. Чтобы повтор не создал второй сервер, передавайте заголовок Idempotency-Key, см. «Известные особенности».
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata.serverId |
Типstring | ОписаниеИдентификатор сервера, на который теперь указывает приложение |
Полеdata.oldServerId |
Типstring | null | ОписаниеИдентификатор прежнего сервера. null, если у приложения сервера не было |
Полеdata.branch |
Типstring | Описаниеexisting — перенос на свой сервер, new — создан новый сервер |
Полеdata.appUrlMoved |
Типboolean | ОписаниеПеренесён ли адрес приложения на новый сервер |
Полеdata.warnings |
Типarray | ОписаниеЧто не удалось довести до конца после переноса. Пустой массив, если всё прошло. Значения — в таблице ниже |
Полеdata.callerKeyManagesServer |
Типboolean | null | ОписаниеУправляет ли новым сервером ключ, которым сделан вызов. null, если платформа не смогла это прочитать |
Значения data.warnings:
| Значение | Что произошло и что делать |
|---|---|
ЗначениеKEY_ASSIGN_FAILED |
Что произошло и что делатьНовый сервер не удалось передать ключу приложения. Приложение указывает на новый сервер, но ключ для управления им назначен не был |
ЗначениеAPP_URL_MOVE_FAILED |
Что произошло и что делатьАдрес приложения не перенесён на новый сервер. Перенесите его вручную |
ЗначениеAPP_URL_MANUAL |
Что произошло и что делатьУ приложения свой адрес, платформа оставила его как есть |
ЗначениеCATALOG_STALE |
Что произошло и что делатьУ прежнего сервера была опубликованная карточка каталога. Опубликуйте карточку заново |
ЗначениеSERVER_KEY_STALE |
Что произошло и что делатьНа выбранном существующем сервере в окружении остался ключ приложения, который отозван или истёк. Обновите ключ в окружении сервера |
ЗначениеLOGIN_SECRET_ROTATED |
Что произошло и что делатьУ приложения встроенный вход, а прежний сервер принадлежал другому человеку, поэтому замена сменила секрет входа. Пользователи приложения выйдут из аккаунтов, админку приложения открывают только владельцы. Настройки почты (SMTP) в админке приложения введите заново |
Пример ответа
{
"success": true,
"data": {
"serverId": "srv_new",
"oldServerId": "srv_old",
"branch": "existing",
"appUrlMoved": true,
"warnings": [],
"callerKeyManagesServer": true
}
}
Пример ответа при ошибке
409 — сервер уже привязан к другому приложению:
{
"success": false,
"error": {
"code": "SERVER_ALREADY_LINKED",
"message": "Server is linked to another application"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодVALIDATION_ERROR |
ОписаниеТело не совпадает ни с { serverId }, ни с { provider, plan, region? } или содержит лишние поля |
| HTTP400 | КодINVALID_IDEMPOTENCY_KEY |
ОписаниеТолько форма new: заголовок Idempotency-Key пустой, длиннее 255 символов или содержит недопустимые символы |
| HTTP400 | КодSERVER_ALREADY_CURRENT |
ОписаниеСервер уже привязан к этому приложению |
| HTTP400 | КодINVALID_PLAN |
ОписаниеТолько форма new: тарифа из plan нет в каталоге провайдера |
| HTTP400 | КодINVALID_REGION |
ОписаниеТолько форма new: региона из region нет в каталоге провайдера |
| HTTP400 | КодPROVIDER_DEPRECATED |
ОписаниеТолько форма new: провайдер выведен из работы |
| HTTP400 | КодKEY_NOT_ELIGIBLE |
ОписаниеТолько форма new: ключ больше не может владеть сервером |
| HTTP401 | КодNO_PORTAL |
ОписаниеКлюч не привязан к порталу |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | КодINVALID_API_KEY |
ОписаниеКлюч не опознан: такой строки на платформе нет |
| HTTP402 | КодACCOUNT_FROZEN |
ОписаниеБаланс портала заморожен. Если закрыты только платные вызовы, перенос на свой существующий сервер работает, а форма new получает этот отказ с userMessage и alternatives |
| HTTP402 | КодCOMMERCIAL_PLAN_REQUIRED |
ОписаниеТолько форма new: платформа не нашла запись портала, к которому привязан ключ, и не может проверить доступ |
| HTTP402 | КодTRIAL_PORTAL_LIMIT |
ОписаниеТолько форма new: исчерпана квота серверов портала на пробном доступе |
| HTTP402 | КодPLAN_NOT_ALLOWED_ON_TRIAL |
ОписаниеТолько форма new: тариф из plan недоступен на пробном периоде. Разрешённые тарифы — в error.details.allowedPlans |
| HTTP402 | КодMARKETPLACE_REQUIRED |
ОписаниеТолько форма new: на портале нет активной подписки BitrixGPT + Маркетплейс, а доступ к платформе открывает она |
| HTTP402 | КодKZ_PAID_ONLY |
ОписаниеТолько форма new: портал из региона KZ, доступ открывает платный или демо-тариф Битрикс24 |
| HTTP402 | КодUZ_PAID_ONLY |
ОписаниеТолько форма new: портал из региона UZ, доступ открывает платный или демо-тариф Битрикс24 |
| HTTP402 | КодBY_PAID_ONLY |
ОписаниеТолько форма new: портал из Беларуси, доступ открывает платный или демо-тариф Битрикс24 либо подписка Битрикс24 Маркет Плюс |
| HTTP402 | КодINT_TARIFF_REQUIRED |
ОписаниеТолько форма new: аккаунт получает доступ по тарифу Битрикс24, нужен коммерческий тариф |
| HTTP402 | КодINT_VIBE_PLUS_REQUIRED |
ОписаниеТолько форма new: на аккаунте Битрикс24 нужен тариф Vibe+ |
| HTTP402 | КодSELFHOSTED_NOT_AVAILABLE |
ОписаниеТолько форма new: коробочный Битрикс24 пока не доступен на этой установке. Покупка тарифа отказ не снимает |
| HTTP403 | КодINFRA_SCOPE_REQUIRED |
ОписаниеУ ключа нет скоупа vibe:infra |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
ОписаниеКлюч только для чтения |
| HTTP403 | КодINFRA_FORBIDDEN_FOR_COWORK_KEY |
ОписаниеКлюч со скоупом vibe:cowork работает только с данными |
| HTTP403 | КодFORBIDDEN |
ОписаниеПриложение принадлежит не владельцу ключа |
| HTTP403 | КодMANAGEMENT_KEY_NO_ENTITY_ACCESS |
ОписаниеУправляющий ключ: нужен личный ключ или ключ авторизации |
| HTTP403 | КодPORTAL_KEY_REQUIRED |
ОписаниеЗапись ключа повреждена и не имеет владельца |
| HTTP403 | КодINFRA_NOT_PERMITTED |
ОписаниеТолько форма new: инфраструктура отключена на платформе или на портале |
| HTTP403 | КодSERVER_CREATION_DISABLED |
ОписаниеТолько форма new: создание серверов запрещено политикой портала |
| HTTP403 | КодSERVER_CREATION_ADMINS_ONLY |
ОписаниеТолько форма new: политика портала разрешает создавать серверы только администраторам |
| HTTP403 | КодVIBE_DEMO_EXPIRED |
ОписаниеТолько форма new: тариф Vibe+ или пробный период закончился |
| HTTP404 | КодAPPLICATION_NOT_FOUND |
ОписаниеПриложения нет на портале ключа |
| HTTP404 | КодSERVER_NOT_FOUND |
ОписаниеСервера нет, он чужой или к приложению его привязать нельзя: это сервер агента, бота или хост галактики |
| HTTP404 | КодPROVIDER_NOT_FOUND |
ОписаниеТолько форма new: провайдер неизвестен или закрыт для этого портала |
| HTTP409 | КодIDEMPOTENCY_KEY_ALREADY_USED |
ОписаниеТолько форма new: ключ Idempotency-Key уже использован с другим приложением или телом, приложение с тех пор перенесено на другой сервер, либо исход прежнего вызова неизвестен |
| HTTP409 | КодIDEMPOTENCY_CONCURRENT_RETRY |
ОписаниеТолько форма new: параллельный запрос занял тот же ключ Idempotency-Key |
| HTTP409 | КодSERVER_ALREADY_LINKED |
ОписаниеСервер привязан к другому приложению |
| HTTP409 | КодAPPLICATION_OP_IN_PROGRESS |
ОписаниеПривязку сервера к приложению меняет другая операция, либо она изменилась во время запроса. Повторите позже |
| HTTP409 | КодREISSUE_IN_PROGRESS |
ОписаниеКлюч приложения или его привязка к серверу заняты перевыпуском ключа, доставкой секретов или удалением. Повторите позже |
| HTTP409 | КодAPPLICATION_KEY_RECOVERY_REQUIRED |
ОписаниеНезавершённая замена ключа блокирует перенос. Завершите или восстановите её |
| HTTP409 | КодPORTAL_ORIGIN_CUTOVER_BUSY |
ОписаниеАдрес портала меняет другая операция, повторите позже |
| HTTP409 | КодAPPLICATION_MOVE_ACTIVE |
ОписаниеПриложение переезжает на новый сервер. В теле — moveId, status и retryAfter (секунды), тот же срок в заголовке Retry-After. Не создавайте новый сервер: подождите и повторите |
| HTTP409 | КодAPPLICATION_MOVE_RETAINING |
ОписаниеПосле переезда прежний сервер хранится для возврата до keepOldUntil. Сначала удалите прежний сервер или дождитесь срока |
| HTTP409 | КодAPP_LOGIN_SDK_NOT_CONFIRMED |
ОписаниеПриложение со встроенным входом, прежний сервер принадлежит другому человеку, а приложение переведено со входа 0.3 и запуск на SDK 0.4 не подтверждён. Ничего не изменилось. Переведите приложение на SDK 0.4 и повторите |
| HTTP429 | КодRATE_LIMITED |
Описание10 запросов в минуту на владельца карточки, каким бы ключом он ни вызывал |
| HTTP429 | КодSERVER_LIMIT |
ОписаниеТолько форма new: достигнут лимит серверов на ключ |
| HTTP429 | КодUSER_SERVER_LIMIT |
ОписаниеТолько форма new: достигнут лимит серверов на человека |
| HTTP502 | КодAPPLICATION_SERVER_ATTACH_FAILED |
ОписаниеНовый сервер создан, но привязать его не удалось. Сервер удалён, приложение осталось на старом |
| HTTP502 | КодPROVIDER_ERROR |
ОписаниеТолько форма new: сбой обращения к облачному провайдеру. В ответе приходит error.incidentCode, назовите его поддержке |
| HTTP502 | КодPROVIDER_NOT_CONFIGURED |
ОписаниеТолько форма new: провайдер не настроен на платформе — у него нет учётных данных или цены для выбранного тарифа. В ответе приходит error.incidentCode |
| HTTP503 | КодPORTAL_ORIGIN_CUTOVER_UNAVAILABLE |
ОписаниеЗащита адреса портала недоступна, повторите позже |
Текст error.message английский и предназначен для журналов: тексты для интерфейса стройте по error.code. Полный список общих ошибок API — Ошибки.
Известные особенности
- Сбой после записи связи не превращается в ошибку. Как только приложение указывает на новый сервер, метод отвечает
200, а то, что довести не удалось, перечисляет вwarnings. Ошибкой ответа бывает только то, что случилось до записи связи. Клиент, который смотрит лишь на статус ответа, пропустит предупреждения: читайтеwarningsвсегда. - Повтор формы
newсIdempotency-Key. Повтор с тем же ключом и тем же телом в течение 24 часов после первого вызова второй сервер не создаёт. Если замена завершилась, ответ200повторяет прежниеdata.serverId,data.oldServerIdиdata.appUrlMovedс пустымdata.warningsи несёт заголовокIdempotent-Replayed: true. Если исход неизвестен или приложение уже перенесено на другой сервер, приходит409 IDEMPOTENCY_KEY_ALREADY_USED. Тогда прочитайтеGET /v1/applications/:id, гдеserver.id— текущий сервер приложения, и проверьте в кабинете, не появился ли отвязанный сервер, прежде чем повторять покупку. Через 24 часа защита от повтора может пропасть. Без заголовка повтор может создать второй сервер. - Ключ вызова не переназначается. Управляющий ключ нового сервера — собственный ключ приложения: ключ авторизации, если он есть, иначе личный ключ. Ключ, которым вы сделали вызов, остаётся прежним. Управляет ли он новым сервером, говорит
callerKeyManagesServer. Этоfalse, когда у приложения есть ключ авторизации или целевой сервер — контейнер галактики. - Сервер создаётся за владельцем карточки. Лимиты и платёжные условия применяются к нему, а не к администратору портала.
- Старый сервер остаётся. Он отвязан от приложения и работает у владельца. Если он вам не нужен, удалите его отдельно через
DELETE /v1/infra/servers/:id. - Приложение со встроенным входом и чужой прежний сервер. Если прежний сервер принадлежит не владельцу карточки, замена вместе с переносом меняет секрет входа: секрет в окружении прежнего сервера перестаёт действовать. Сессии пользователей приложения завершаются, а админка входа открыта только его владельцам: администраторы без отметки владельца в неё не попадают. База входа на диске прежнего сервера и в его резервных копиях остаётся. О смене говорит значение
LOGIN_SECRET_ROTATEDвdata.warnings. Если прежний сервер ваш, секрет не меняется. - Показывать кнопку или нет, решает
available-servers. Он же заранее называет причину отказа для формыnew. Остальные причины приходят кодами ошибок из таблицы выше.