Для AI-агентов: markdown этой страницы — /docs-content/errors/platform.md индекс документации — /llms.txt

Битрикс24 и платформа

Подробный разбор кодов, которыми API Вайбкод отвечает, когда операцию отклонил Битрикс24 или сбой произошёл на самой платформе.

Сводная таблица всех кодов API Вайбкод — Коды ошибок.

`BITRIX_ERROR` (422)

Битрикс24 вернул бизнес-ошибку, которая не подпадает под более узкие категории (ACCESS_DENIED, NOT_FOUND, INVALID_PARAMS, RATE_LIMITED).

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "The requested period exceeds the maximum of 1 year",
    "b24Code": "PERIOD_TOO_LARGE"
  }
}

Причины:

  • Битрикс24 отверг операцию по бизнес-причине: несовместимое состояние, неподдерживаемое значение, бизнес-правило.
  • Запрос работает на портале, где соответствующий модуль отключён.

Решение:

  • Прочитать message — там оригинальный текст ошибки от Битрикс24.
  • При наличии hint — использовать его как первый шаг диагностики.
  • Для программной обработки читать поле error.b24Code — машиночитаемый код причины от Битрикс24, например BOT_TYPE_NOT_ALLOWED или PERIOD_TOO_LARGE. Ветвиться в коде по нему, а не по тексту message. Когда Битрикс24 не прислал отдельный код, поля в ответе нет — предусмотрите ветку по умолчанию.

`METHOD_NOT_YET_AVAILABLE` (422)

Метод выходит в обновлении Битрикс24, которое на этот портал ещё не приехало. Это признак раскатки, а не ошибка вызова: тот же запрос начнёт работать сам, как только обновление дойдёт до портала. На отдельных методах после этого добавляется своя проверка прав — она описана на странице метода.

JSON 
{
  "success": false,
  "error": {
    "code": "METHOD_NOT_YET_AVAILABLE",
    "message": "Method \"imopenlines.v2.Stat.get\" is rolling out in update imopenlines 26.700.0 and is not yet available on this portal — this is not a call error.",
    "release": "imopenlines 26.700.0"
  }
}

Решение:

  • Ветвиться по error.code, а не по тексту message.
  • Поле error.release — идентификатор обновления целиком: имя модуля и номер версии одной строкой. Сравнивать его на равенство как строку, разбирать как номер версии нельзя.
  • Частые повторы ничего не меняют: состояние переключается приездом обновления на портал, а не повтором вызова. Заголовка Retry-After и поля retryAfter в этом отказе нет, потому что срока платформа не знает. Пока обновление не пришло, показывайте пользователю ожидание названной версии, а не ошибку интеграции.

`BITRIX_UNAVAILABLE` (502)

Битрикс24 вернул 5xx или не ответил в отведённое время.

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_UNAVAILABLE",
    "message": "Bitrix24 returned 503 Service Unavailable"
  }
}

Причины:

  • Технические работы или перегрузка на стороне Битрикс24.
  • Сетевые проблемы между Вайбкод и порталом.

Решение:

  • Повторить запрос через несколько минут, реализовав повторные попытки с экспоненциальной задержкой.
  • Для записывающих операций (POST/PATCH) — сначала проверьте, не применился ли исходный запрос. Медленный портал может обработать запись уже после того, как ответ ушёл клиенту, и слепой повтор создаст дубль. Порядок проверки — тот же, что у BITRIX_TIMEOUT.

`BITRIX_TIMEOUT` (503)

Битрикс24 принял запрос, но не ответил за 15 секунд — исход неизвестен: запрос МОГ примениться на стороне портала.

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_TIMEOUT",
    "message": "Bitrix24 request timed out after 15s",
    "hint": "Bitrix24 accepted the request but did not respond within the configured time limit. For WRITE operations, verify whether the change was applied (re-read the entity) before retrying. Reads are safe to retry.",
    "retryAfter": 10
  }
}

Решение:

  • Для чтения (GET//search) — повторить безопасно, после более длинной паузы, чем при 429.
  • Для записывающих операций (POST/PATCH) — сначала перечитайте сущность. Изменение могло уже примениться на стороне Битрикс24, несмотря на то, что ответ не пришёл. Слепой повтор создаст дубль (задачи, эпика, комментария). Проверьте наличие записи (например, поиск по только что отправленному названию) и повторяйте запись только если её нет.

`INTERNAL_ERROR` (500)

Непредвиденная ошибка на стороне API Вайбкод.

JSON 
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

Решение:

  • Повторить запрос.
  • Если ошибка воспроизводится стабильно — отправить тикет через POST /v1/feedback с указанием времени запроса. Заголовок X-Request-Id из ответа ускоряет диагностику.

Смотрите также