Изменения API: 13 сентября 2026

← Журнал изменений · Сентябрь 2026

FIX-0913-1: описание API называет отказы, общие для всех операций

Было

Машинное описание (/v1/openapi.json) не называло отказы, которые отдают не сами ручки, а общие слои платформы, — и клиент, собранный по описанию генератором, встречал их как неизвестный ответ.

Отказ по балансу 402 ACCOUNT_FROZEN (счёт заморожен за долг) возможен на любой операции с ключом, кроме нескольких информационных и служебных, — а описан был у 22 операций из 842. Ответы 429 RATE_LIMITED (Битрикс24 ограничил частоту), 429 ERROR_LOOP_DETECTED, 429 QUEUE_OVERFLOW, 429 QUEUE_TIMEOUT, 429 OPERATION_TIME_LIMIT, 429 TIMEOUT_QUARANTINE, 502 BITRIX_UNAVAILABLE (портал недоступен) и 503 BITRIX_TIMEOUT (портал не ответил в срок) возможны на каждой операции, обращающейся к порталу, — 502 BITRIX_UNAVAILABLE был описан у 11 операций, 503 BITRIX_TIMEOUT у 4, остальные почти нигде. Операции шаблонов, роботов и действий бизнес-процессов (/v1/bizproc-templates, /v1/bizproc-robots, /v1/bizproc-activities) отвечают личному ключу 403 OAUTH_REQUIRED — описание молчало; GET /v1/triggers описывал только успех, тогда как личному ключу портал отвечает 403 BITRIX_ACCESS_DENIED. Ответ 400 INVALID_PARAMS на нечисловой номер записи в пути не был описан у чтения записи ни одной сущности с числовым номером (GET /v1/tasks/{id}, GET /v1/workgroups/{id} и остальных) и у большинства подчинённых ручек задач, скрама, таймлайна и журнала таймлайна.

Стало

Поведение ручек не менялось — исправлено описание. Успешные ответы по-прежнему те же 200, 201 и 204, что и были: меняется описание отказов, не ответ.

402 ACCOUNT_FROZEN описан ровно у тех операций, которые общий гейт заморозки может отбить: у всех операций с ключом, кроме GET /v1/me, GET /v1/me/sources, GET /v1/guide, четырёх вызовов переписки по обращению (GET /v1/feedback, POST /v1/feedback, GET /v1/feedback/{id}, POST /v1/feedback/{id}/comments) и DELETE /v1/cowork/key. В описании названо, что отказ приходит до любых проверок самой операции и всегда в общем конверте ответа (на OpenAI-совместимых операциях ИИ тоже), и что по мере раскатки сужения отказ останется только у операций, оплачиваемых кошельком, — успешный ответ на замороженном счёте не означает, что счёт в порядке (состояние — в infraState ответа GET /v1/me).

429, 502 и 503 с перечисленными выше кодами описаны у операций, обращающихся к порталу: у сгенерированных операций сущностей (список, чтение, создание, правка, удаление, поиск, пакет, импорт, агрегация, связи, товарные позиции, действия — кроме GET /v1/{entity}/fields, которая при отказе портала отвечает 200 со статическим набором полей и предупреждением fields_partial), у пакетного вызова POST /v1/batch (там свой набор: лимит Битрикс24 на самом конверте приходит не как 429, а как 502 BITRIX_UNAVAILABLE в штатной форме или 422 BITRIX_ERROR, с кодом портала в error.bitrixError.error; 429 там — лимит пакетов и очередь) и у рукописных семей: подчинённые ручки задач, скрам, таймлайн, журнал таймлайна, рабочий день, звонки, бизнес-процессы (/v1/workflows), пользовательские поля CRM (/v1/userfields), история стадий, загрузка файлов, поиск дублей, GET /v1/addresses/fields, POST /v1/doc-templates. Там, где у операции уже был свой 429 (лимит чтений или пакетов, свой лимит ручки), свой 502 или 503, прежний текст сохранён и дополнен. У каждой такой операции описан и 422 BITRIX_ERROR — общий ответ на ошибку портала, не подпадающую под более узкий код.

У всех операций трёх сущностей бизнес-процессов описан 403 OAUTH_REQUIRED; у записывающих — рядом с WRITE_BLOCKED_READONLY_KEY. GET /v1/triggers и POST /v1/triggers/fire описывают 401, 403 (SCOPE_DENIED, BITRIX_ACCESS_DENIED, у запуска — и WRITE_BLOCKED_READONLY_KEY), 422 и, у запуска, 400 (MISSING_PARAMS, INVALID_ENTITY_TYPE, INVALID_ENTITY_TYPE_ID).

400 INVALID_PARAMS на нечисловой номер записи описан у чтения, правки и удаления записи каждой сущности с числовым номером и у подчинённых ручек задач, скрама, таймлайна, журнала таймлайна, расшифровки звонка (GET /v1/activities/{activityId}/transcript), участников рабочей группы и конвертации лида. Свои коды того же отказа названы там, где ручка отвечает ими: INVALID_DYNAMIC_PARAM (все операции смарт-процессов по {entityTypeId}), INVALID_ENTITY_TYPE_ID (запись смарт-процесса, пользовательские поля смарт-процессов, конфигурация карточки CRM), INVALID_ROW_ID (товарная позиция), INVALID_ANCHOR (связи реквизитов), VALIDATION_ERROR (настраиваемые дела), INVALID_ID (фото сотрудника), INVALID_BOT_ID (передача бота), UNKNOWN_ENTITY (пользовательские поля CRM по {entity}).

Что описание ПО-ПРЕЖНЕМУ не называет — сознательно: отказ по суточной квоте вызовов (429 QUOTA_EXCEEDED) — общий для всего API и не входит в это изменение; у пакетных чтений, которые сообщают отказ портала внутри успешного ответа по каждому под-вызову (POST /v1/mail/mailboxes/batch, POST /v1/tasks/{taskId}/comments/batch), отказы портала на уровне ответа не описаны — их там нет.

Общие ответы вынесены в переиспользуемые компоненты описания AccountFrozen, PortalRateLimited, PortalUnavailable, PortalTimeout и OauthAppKeyRequired. Интерактивный справочник (/docs → API reference) перегенерирован из исправленного описания. Подробности по кодам — на странице Ошибки.

NEW-0913-2: приложение Partner Connect запрашивает право vibe:ai само

vibe:ai теперь перечисляется в правах Connect-приложения при регистрации и правке — как любое право Битрикс24, без заявки и проверки. Дальше право идёт обычным путём: приложение передаёт его в параметре scope у /v1/connect/authorize, пользователь видит строку «AI-модели» на экране согласия и подтверждает набор целиком, и выданный ключ несёт это право. Вызовы AI-роутера таким ключом работают, расход покрывает месячный AI-лимит аккаунта.

Автоматически право не добавляется: приложение, которое его не запросило, работает как раньше, и у ранее выданных ключей набор прав не меняется. Остальные платформенные права — vibe:search, vibe:infra, vibe:storage, vibe:feedback — выдаёт платформенный администратор, и запрос с ними при саморегистрации отклоняется кодом SCOPE_NOT_ALLOWED. Документ /.well-known/oauth-authorization-server перечисляет vibe:ai в поле scopes_supported.

FIX-0913-3: товарные позиции несуществующей записи отвечают «не найдено», как соседние методы

Было

GET /v1/deals/{id}/products по несуществующему id отвечал 403 BITRIX_ACCESS_DENIED — так Битрикс24 отвечает на запрос товарных позиций у владельца, которого нет, и Вайбкод передавал этот ответ как есть. Соседние методы на тот же id — сама запись, её контакты, запись товарных позиций — отвечали 404 ENTITY_NOT_FOUND. Клиент, получив «доступ запрещён», шёл проверять права вместо того, чтобы проверить id. То же у лидов, предложений, счетов и элементов смарт-процессов.

Стало

Получив от Битрикс24 отказ на чтение товарных позиций, Вайбкод один раз проверяет саму запись — тем же вызовом, что и GET /v1/{entity}/{id}. Записи нет — ответ 404 ENTITY_NOT_FOUND, как у соседних методов. Запись есть, но закрыта правами сотрудника, — по-прежнему 403 BITRIX_ACCESS_DENIED. Успешные запросы дополнительного вызова не делают. В OpenAPI у метода объявлен ответ 404; страница счетов больше не описывает 403 как ответ на несуществующую запись.

Затронутые эндпоинты: GET /v1/deals/{id}/products, GET /v1/leads/{id}/products, GET /v1/quotes/{id}/products, GET /v1/invoices/{id}/products, GET /v1/items/{entityTypeId}/{id}/products.

FIX-0913-4: заморозка счёта проверяется у ключа приложения и без сессии пользователя

Было

Ключ приложения (vibe_app_*), присланный без заголовка Authorization: Bearer с сессией пользователя, на заморозку счёта не проверялся: вызов шёл дальше, к собственным проверкам операции. На замороженном счёте такой ключ проходил в двери, которые оплачиваются балансом Вайбкод, — создание приложения с парным ключом, загрузку и скачивание вложений обращений, правку обращения, поиск и глубокий поиск, список серверов — тогда как личный ключ и тот же ключ приложения с сессией получали 402 ACCOUNT_FROZEN.

Стало

Заморозка — состояние счёта, а не сессии: на замороженном счёте ключ приложения без сессии отвечает 402 ACCOUNT_FROZEN ровно там же, где личный ключ, — состав закрытых и открытых вызовов описан в разделе «Что закрывает заморозка счёта». Открытые под заморозкой вызовы — самоописание, справочник, спека, переписка по обращениям — открыты и для такого ключа. На счёте без заморозки ответы не меняются: успешный ответ сохраняется.

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

Клиент ничего не меняет. Если интеграция ходила ключом приложения без сессии и на замороженном счёте вдруг получила 402 ACCOUNT_FROZEN — это не поломка ключа, а долг: пополните баланс, состояние счёта видно в блоке infraState ответа GET /v1/me.

FIX-0913-5: пакетный вызов отвечает 429 ERROR_LOOP_DETECTED, а не 500, когда платформа приостановила его после серии отказов

Было

Когда пакетные вызовы одного ключа раз за разом отклонялись порталом и платформа Вайбкод временно приостанавливала их (см. ERROR_LOOP_DETECTED), сам POST /v1/batch отвечал 500 INTERNAL_ERROR без заголовка Retry-After и без подсказки, — тогда как любая другая операция в том же состоянии отвечает 429 ERROR_LOOP_DETECTED. Клиент читал внутреннюю ошибку платформы там, где действовал её же защитный механизм, и не знал, сколько ждать.

Стало

POST /v1/batch отвечает 429 ERROR_LOOP_DETECTED с заголовком Retry-After, а в error.message и error.hint — число отказов за последний час и с какой частотой пробные запросы пропускаются для проверки, что серия закончилась. Отдельные вызовы внутри пакета и раньше получали этот код в data.errors.<id> — изменился только ответ на весь пакет.

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

Ничего менять не нужно. Обработчик, который на 429 ERROR_LOOP_DETECTED выдерживает паузу из Retry-After, теперь срабатывает и на пакетном вызове. Если на 500 от пакетного вызова была настроена тревога — она перестанет срабатывать на этом состоянии.