Коды ошибок

Об ошибке Битрикс24 сообщает JSON-структурой с полями error и error_description. Структура приходит в теле ответа вместо данных, которые метод вернул бы при успешном вызове. Так устроен ответ на одиночный вызов — у пакета batch ошибки подзапросов приходят иначе, внутри result:

{
    "error": "ERROR_HANDLER_ALREADY_EXIST",
    "error_description": "Handler already exists!"
}

Код ERROR_HANDLER_ALREADY_EXIST из примера вернул конкретный метод — в перечень системных ошибок он не входит.

Здесь собраны системные коды — те, что REST API возвращает в ответ на любой метод. Коды конкретного метода и коды сервера авторизации перечислены на других страницах — где искать нужный код, показывает раздел Где описан код ошибки.

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Поля ответа с ошибкой

Название `тип`	Описание
error `string`	Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только `error_description`
error_description `string`	Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Как распознать ошибку в ответе

Ошибку распознавайте по составу полей в теле ответа, а не по HTTP-статусу: со статусом 200 приходят ошибки подзапросов batch. Статус нужен для другого — записывайте его в лог вместе с кодом, он помогает при разборе инцидента.

Что в теле ответа	Что это значит	Что делать
Есть поле `result`, а поле `result.result_error` пустое или отсутствует	Вызов выполнен	Разобрать данные из `result`
Есть поля `error` и `error_description`	Вызов не выполнен	Разобрать ошибку: если код в `error` есть, найти его в перечне системных ошибок или на странице метода, если поле пустое — читать `error_description`
Поле `result.result_error` непустое	Пакет batch принят, но часть подзапросов завершилась ошибкой	Разобрать ошибки подзапросов по ключам команд

Поле result.result_error есть в ответе batch всегда: в успешном пакете оно приходит пустым — "result_error": []. Признак ошибки — записи в этом поле, а не само его наличие. Ошибку подзапроса batch возвращает по тому же ключу, под которым команда была передана в запросе. Устройство ответа batch разобрано на его странице.

Поле error может прийти пустым — тогда причину показывает только error_description. Так приходят ошибки конкретного метода — чаще всего это ошибки проверки параметров и поиска объекта. Например, запрос сделки с несуществующим идентификатором возвращает статус 400 и тело {"error": "", "error_description": "Not found"}. Проверяйте в ответе наличие ключа error, а не его значение:

// адрес url собирают по правилам из раздела «Как выполняется запрос»,
// имя метода нужно здесь только для лога
async function callMethod(method, url) {
    const response = await fetch(url);
    const data = await response.json();

    // вызов не выполнен: проверяем наличие ключа error, а не его значение
    if ('error' in data) {
        // код отдаем отдельным полем, чтобы вызывающий код ветвился по нему,
        // а статус и имя метода остаются для лога
        const error = new Error(data.error_description);
        Object.assign(error, { code: data.error, status: response.status, method });
        throw error;
    }

    // ошибки подзапросов batch лежат по ключам команд
    // в успешном пакете поле приходит пустым, поэтому считаем записи, а не проверяем наличие
    const batchErrors = data.result?.result_error ?? {};

    // повторить подзапросы или прервать сценарий — решает вызывающий код
    return {
        result: data.result,
        batchErrors,
        hasBatchErrors: Object.keys(batchErrors).length > 0
    };
}

Разбирать ответ вручную нужно не всегда: SDK Битрикс24 снимают проверку полей и отдают ошибку средствами языка. В каком виде приходит код ошибки, зависит от библиотеки — смотрите страницу нужного SDK. Реакцию на конкретный код интеграция задает сама, поэтому правила ниже применимы и при работе через SDK.

В формате XML те же данные приходят элементами <error> и <error_description> внутри <response>. Как выбрать формат ответа, описано на странице Как выполняется запрос.

Где описан код ошибки

Перечень кодов зависит от того, какая часть Битрикс24 вернула ошибку.

Источник ошибки	Когда возникает	Где описаны коды
REST API Битрикс24	При работе самого REST API: неверные авторизационные данные, нехватка прав, превышение лимитов, недоступность REST API	Статусы и коды системных ошибок на этой странице
Конкретный метод	При нарушении правил самого метода: неверный формат параметра, отсутствие объекта, недопустимое значение поля	Раздел «Обработка ошибок» на странице метода — например, у метода crm.item.add там перечислены коды, специфичные для создания элемента смарт-процесса
Сервер авторизации `oauth.bitrix24.tech`	При обмене авторизационного кода на токены и при их продлении	Коды ошибок сервера авторизации

Ошибки метода описаны на его странице, потому что зависят от состава параметров и состояния объекта.

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит
`401`	`NO_AUTH_FOUND` Wrong authorization data	В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука
`401`	`INVALID_REQUEST` Https required	Методы вызываются только по протоколу HTTPS
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на `provided by the access token`
`401`	`expired_token` The access token provided has expired	Срок действия access-токена истек
`401`	`user_access_error` The user does not have access to the application	Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям
`403`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Как обрабатывать ошибки в интеграции

Ветвитесь по коду из поля error, а не по тексту из error_description. Текст ошибки метода приходит на языке интерфейса Битрикс24 и может измениться, поэтому опорой для ветвления он быть не может.

Реакция на системные коды

Порядок строк совпадает с порядком в таблице системных ошибок выше, причины ошибок описаны в ней.

Код	Что делать
`INTERNAL_SERVER_ERROR`, `ERROR_UNEXPECTED_ANSWER`	Повторить вызов через несколько секунд. Если ошибка сохраняется, обратиться к администратору сервера в коробочной версии или в техническую поддержку
`QUERY_LIMIT_EXCEEDED`	Снизить интенсивность запросов и повторить вызов позже. Допустимая интенсивность по тарифам — в лимитах REST API
`OPERATION_TIME_LIMIT`	Приостановить вызовы этого метода. Ориентир для первой повторной попытки — поле `operating_reset_at` из блока `time` последнего успешного ответа. Если попытка снова уперлась в лимит, дождаться следующего сброса: механика описана в лимитах REST API
`NO_AUTH_FOUND`	Передать в запросе access-токен или код вебхука: в текущем запросе их нет
`INVALID_REQUEST`	Заменить `http` на `https` в адресе запроса
`OVERLOAD_LIMIT`	Не повторять вызов и обратиться в техническую поддержку: блокировка ручная и сама не снимется
`ACCESS_DENIED` со статусом `401`	Перейти на коммерческий тариф. С другим статусом этот код возвращает метод — смотрите пояснение после таблицы
`INVALID_CREDENTIALS`	Проверить идентификатор пользователя и код вебхука в адресе запроса: активный вебхук с такой парой не найден
`ERROR_METHOD_NOT_FOUND`	Проверить написание имени метода и наличие нужного скоупа
`insufficient_scope`	Добавить недостающий скоуп в приложение или в вебхук
`expired_token`	Продлить токены и повторить вызов
`user_access_error`	Попросить администратора Битрикс24 открыть пользователю доступ к приложению
`PORTAL_DELETED`	Открыть публичную часть сайта: пока она закрыта, REST API не ответит

Один и тот же код может встретиться и в системном перечне, и в перечне конкретного метода — тогда их различает HTTP-статус. Системные ошибки авторизации и доступа приходят со статусом 401, ошибки метода — с 400 или 403. Например, ACCESS_DENIED со статусом 401 означает, что REST API недоступен на текущем тарифе, а тот же код со статусом 403 и текстом Access denied! Application context required вернул метод, которому нужен контекст приложения.

Повтор вызова, который вернул ошибку метода, даст тот же результат — сначала исправьте запрос.

Что писать в лог

Записывайте в лог интеграции error, error_description, HTTP-статус и имя вызванного метода. Авторизационные данные — токены и коды вебхуков — в лог не пишите: по ним можно получить доступ к данным Битрикс24.

Продолжите изучение

Была ли статья полезна?

Лимиты REST API

Митапы для разработчиков

Коды ошибок

Поля ответа с ошибкойПоля ответа с ошибкой

Как распознать ошибку в ответеКак распознать ошибку в ответе

Где описан код ошибкиГде описан код ошибки

Статусы и коды системных ошибокСтатусы и коды системных ошибок

Как обрабатывать ошибки в интеграцииКак обрабатывать ошибки в интеграции

Реакция на системные кодыРеакция на системные коды

Похожие коды, которые возвращают методыПохожие коды, которые возвращают методы

Что писать в логЧто писать в лог

Продолжите изучениеПродолжите изучение