Обработка ошибок и коды ответов

Любой ответ REST Битрикс24 при ошибке возвращает JSON с полями error и error_description. Надёжная интеграция различает временные сбои (стоит повторить) и постоянные (нужно чинить код или права), опираясь на код ошибки и HTTP-статус.

Структура ответа при ошибке

Успешный ответ содержит поле result. При ошибке вместо него приходит объект с машинным кодом и человекочитаемым описанием:

{ "error": "expired_token", "error_description": "The access token provided has expired." }

• error — короткий машинный код, по нему строят логику обработки.
• error_description — пояснение для человека и логов.

Опираться в коде нужно на error, а не на текст описания: формулировки могут меняться, коды стабильнее.

HTTP-коды ответов

REST Битрикс24 использует и HTTP-статусы, и коды в теле. Ориентируйтесь на оба: статус даёт класс проблемы, поле error — конкретику.

Частые коды ошибок

Набор кодов, которые встречаются чаще всего, и что за ними стоит:

• expired_token / invalid_token — токен доступа истёк или недействителен; нужно обновить через refresh-токен (для OAuth-приложений).
• QUERY_LIMIT_EXCEEDED — превышен лимит частоты запросов; повторить позже.
• OPERATION_TIME_LIMIT — исчерпан операционный лимит нагрузки метода.
• ERROR_METHOD_NOT_FOUND — метод не существует или недоступен в текущем scope.
• insufficient_scope — приложению не выдано право на этот раздел API.
• ACCESS_DENIED — у пользователя нет прав на объект или действие.
• INVALID_CREDENTIALS — неверные учётные данные вебхука/приложения.

Временные и постоянные ошибки

Ключевое решение при обработке — повторять запрос или нет. Разделяйте ошибки на два класса:

Стратегия повторов

Грамотный retry строится на экспоненциальной задержке с ограничением числа попыток:

1. При временной ошибке ждём базовую паузу (например, 1 секунду).
2. Каждую следующую попытку удваиваем задержку: 1, 2, 4, 8 секунд.
3. Ограничиваем число повторов (например, 5) и общий тайм-аут.
4. Для OPERATION_TIME_LIMIT опираемся на operating_reset_at из блока time и ждём до сброса окна.
5. При expired_token сначала обновляем токен, потом повторяем без задержки.

Все неуспешные попытки логируйте с кодом ошибки, методом и параметрами — это резко ускоряет разбор инцидентов.

Ошибки внутри batch

Отдельный случай — ошибки в пакетных запросах. Метод batch может вернуть HTTP 200, но при этом часть вложенных команд провалится. Ошибки лежат не в корне ответа, а в result.result_error с ключами по именам команд.

Правильная обработка:

• Всегда проверять result_error, даже при статусе 200.
• Сопоставлять ошибки с именами команд, чтобы понять, какая операция не прошла.
• Учитывать halt: при halt=1 часть команд могла не запуститься вовсе.

Не полагайтесь на один лишь HTTP-статус пакета — он не отражает судьбу отдельных команд.

Идемпотентность и логирование

Повторы неизбежно порождают риск дублей: запрос мог выполниться на портале, но ответ потеряться в сети — и retry создаст второй объект. Чтобы этого избежать, проектируйте операции идемпотентно.

• Внешний ключ. Храните на своей стороне идентификатор внешней системы и перед созданием проверяйте, нет ли уже такого объекта (например, поиском по UF_*-полю).
• Upsert вместо add. Где возможно, сначала ищите объект, затем решайте — add или update.
• Журнал операций. Логируйте каждый запрос: метод, параметры, HTTP-статус, поле error и время. Это ускоряет разбор инцидентов в разы.

Наблюдаемость — не роскошь, а условие эксплуатации. Без журнала «данные иногда не доезжают» превращается в неразрешимую загадку, а с журналом видно конкретный код ошибки и запрос, на котором всё сломалось.

Итог

Обработка ошибок в REST Битрикс24 строится на чтении поля error, HTTP-статуса и блока time. Разделяйте временные ошибки (повтор с backoff) и постоянные (правка кода или прав), обновляйте токен по expired_token и обязательно проверяйте result_error внутри batch.

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