Изменения API: 17 июля 2026

← Журнал изменений · Июль 2026

FIX-0717-1: деплой на спящий galaxy-хост отвечает раньше клиентских таймаутов

Было

POST /v1/infra/servers/:id/deploy на спящем общем хосте удерживал соединение открытым до ~6,5 минут, пока хост просыпался. HTTP-клиенты с типовым таймаутом ожидания заголовков (~300 секунд — дефолт Node fetch) обрывали соединение раньше ответа платформы: деплой выглядел как сетевой сбой fetch failed без кода ошибки и рекомендаций. Неудачное пробуждение к тому же возвращало хост в сон, и каждый повтор начинал загрузку хоста заново.

Стало

Платформа будит хост в фоне и ждёт подключения не дольше ~4 минут. Хост успел подключиться — деплой выполняется одним вызовом, как раньше. Не успел — сразу возвращается повторяемый 502 GALAXY_HOST_UNREACHABLE с hint (повторить тот же запрос через 1–2 минуты, слот не удалять), а хост продолжает просыпаться в фоне — повторный деплой подхватывает уже идущую загрузку вместо новой. В deployment.galaxyApp._rules и deployment.standalone._rules (GET /v1/me) добавлена рекомендация держать таймаут HTTP-клиента не ниже 690 секунд — строго выше платформенного окна в 660 секунд.

Влияние на интеграторов

Изменений в запросах не требуется. Если деплой на спящий galaxy-хост раньше завершался у вас сетевой ошибкой без ответа платформы — теперь придёт либо успех, либо 502 с инструкцией повторить.

NEW-0717-2: поиск сотрудников на сервере подсказывает причину пустого списка

Эндпоинт GET /v1/infra/servers/:id/b24-users теперь возвращает дополнительное поле hint, когда список пуст из-за отсутствия доступа к Битрикс24 — приложение ещё не авторизовано на портале или ключ отозван. Прежние вызовы работают без изменений: поле аддитивное и отсутствует при успешной выдаче.

NEW-0717-3: справочники полей каталога сообщают о nullable-полях

Справочники GET /v1/catalog-prices/fields, GET /v1/catalog-sections/fields и GET /v1/catalog-products/fields теперь добавляют ключ "nullable": true полям, которые могут вернуть null: у цен это quantityFrom, quantityTo и extraId, у разделов — iblockSectionId, xmlId, code и description, у товаров — iblockSectionId, code, weight, purchasingPrice, purchasingCurrency, quantity и quantityReserved. Тот же признак приходит в data.entities[].fieldsDetailed ответа GET /v1/guide, который читается ключом OAuth-приложения без сессии, а в машинной спеке GET /v1/openapi.json такие поля описаны union-типом вида ["number", "null"]. Клиент, который строит типизированную модель по справочнику, теперь получает верную nullability и не падает на первом же null. Набор полей, их типы и значения в ответах не изменились.

NEW-0717-4: EXEC_BUSY подсказывает, через сколько повторить

Ответ 409 EXEC_BUSY (другая операция держит блокировку сервера) на POST /v1/infra/servers/:id/exec и POST /v1/infra/servers/:id/deploy теперь несёт retry-подсказку: HTTP-заголовок ответа Retry-After (в секундах) и два новых поля в теле ошибки — retryable: true и retryAfter (в секундах). Значение retryAfter — короткий интервал опроса (повторяйте с ним, пока не пройдёт), а не полное время до автоматического снятия блокировки; полный верхний предел по-прежнему в error.hint.autoExpiresInSeconds. Изменение аддитивное: код, поле message и hint не меняются, клиенты, читающие error.code, продолжают работать без правок.

FIX-0717-5: деплой galaxy-приложения со слишком большим архивом отдаёт 413, а не «хост недоступен»

Было

POST /v1/infra/servers/:id/deploy с source.content, превышающим лимит загрузки, возвращал 502 GALAXY_HOST_UNREACHABLE — с текстом про недоступность хоста и советом «повторить, когда хост переподключится». Хост при этом был полностью доступен, а повтор того же архива давал тот же результат: интегратор оказывался в бесконечном цикле бесполезных попыток.

Стало

Тот же случай возвращает 413 GALAXY_UPLOAD_TOO_LARGE со структурированным error.hint. Причина детерминирована (архив слишком большой), а не транзиентна, поэтому повтор без изменений не поможет. hint подсказывает уменьшить архив — исключить node_modules, .git и артефакты сборки (зависимости платформа ставит на хосте). У galaxy-приложения источник — только встроенный source.content (source.url отклоняется с 400 GALAXY_DEPLOY_CONTENT_ONLY), поэтому уменьшить архив — единственный способ восстановления. Отдельный смежный случай: тело запроса, превышающее жёсткий внешний лимит платформы (500 МБ на base64-тело ≈ ~375 МБ бинарного архива), теперь отклоняется на краю кодированным 413 PAYLOAD_TOO_LARGE (на Vibe-REST /v1/-маршрутах — deploy/upload/create; OpenAI-совместимые AI-роуты отдают ошибку в своём конверте) вместо сырого HTML — раньше клиент получал недекодируемый ответ.

Влияние на интеграторов

Ничего менять не нужно: успешные деплои не затронуты. Клиенты, которые ветвились на коде ошибки для этого сбоя, теперь видят честный 413 GALAXY_UPLOAD_TOO_LARGE вместо вводящего в заблуждение 502 GALAXY_HOST_UNREACHABLE — последний остаётся для настоящего обрыва туннеля во время сборки.

NEW-0717-6: displayName и description в деплое задают карточку в каталоге Битрикс24

POST /v1/infra/servers/:id/deploy принял два необязательных поля тела — displayName и description. POST /v1/infra/servers (создание сервера) принял необязательный description. Значения становятся именем и описанием карточки приложения в каталоге Битрикс24. Если деплой прошёл без displayName и description, ответ содержит warnings: string[] с подсказкой задать их; одношаговое создание galaxy-приложения с source (тело POST /v1/infra/servers с полем source) тоже возвращает warnings в ответе 201, когда поля не заданы. Обратная совместимость сохранена — запросы без новых полей продолжают работать как раньше.

FIX-0717-7: деплой галактик отдаёт 503 при временной перегрузке базы

Было

При кратковременном исчерпании пула соединений с базой во время деплоя приложения в галактику POST /v1/infra/servers/:id/deploy возвращал общий 502 GALAXY_APP_DEPLOY_FAILED — тот же код, что и настоящий провал сборки. Клиент не мог отличить временную перегрузку от терминальной ошибки и часто читал ответ как окончательный.

Стало

Временная перегрузка базы теперь отдаётся как 503 POOL_EXHAUSTED с заголовком Retry-After (число секунд для повторной попытки). Настоящий провал сборки по-прежнему 502 GALAXY_APP_DEPLOY_FAILED.

Влияние на интеграторов

Ничего менять не нужно. Если ваш клиент повторяет запросы, теперь на 503 он получает явный сигнал бэкоффа через Retry-After вместо непрозрачного 502.

FIX-0717-8: фильтр и сортировка списка комментариев задачи работают на обеих карточках

Было

Запрос GET /v1/tasks/:taskId/comments с параметром filter или с сортировкой не по ID на портале с новой карточкой задачи возвращал 200 и пустой список, даже когда комментарии в задаче были. Ошибки не приходило, поэтому отличить «под фильтр ничего не подошло» от «фильтр не сработал» было нельзя.

Стало

Такой запрос возвращает подошедшие комментарии. Фильтр и сортировка работают по полям ID, AUTHOR_ID и POST_DATE, перед именем поля в фильтре допустим префикс !, >, >=, < или <=. Фильтр по AUTHOR_NAME и сортировка по AUTHOR_NAME или AUTHOR_EMAIL на новой карточке отвечают 400 с кодом UNSUPPORTED_FILTER_FIELD или UNSUPPORTED_SORT_FIELD и указывают на AUTHOR_ID, на старой карточке эти поля по-прежнему принимаются. Добавлен параметр offset — он учитывается на новой карточке при запросе с filter или сортировкой не по ID, на остальных путях чтения игнорируется. Код INVALID_FILTER теперь приходит ещё и тогда, когда filter — скаляр или пустой массив вместо объекта (0, false, "", []), значение поля ID или AUTHOR_ID не число, значение POST_DATE не разбирается как дата, либо значение поля — объект или массив вместо скаляра. В meta добавлено поле truncated со значением true — просмотрено предельное окно истории, и часть комментариев осталась за его границей.

Влияние на интеграторов

Менять ничего не нужно: запрос, который раньше отдавал пустой список, начинает отдавать данные. Учтите три границы. Первая — фильтр по AUTHOR_NAME и сортировка по AUTHOR_NAME или AUTHOR_EMAIL на портале с новой карточкой вместо пустого 200 теперь отвечают 400, переведите такой запрос на AUTHOR_ID, идентификатор сотрудника по имени даёт GET /v1/users. Вторая — meta.total на запросе с фильтром к новой карточке считает подошедшие комментарии в пределах просмотренного окна, а не во всей истории задачи, и при meta.truncated: true это неполное число. Третья — значение POST_DATE на новой карточке сравнивается с createdAt в UTC, поэтому результат на границе суток может отличаться от выборки на старой карточке. На порталах со старой карточкой поведение не изменилось.