5 ошибок при разработке API
REST API Битрикс24 кажется простым: отправил запрос, получил ответ. Но когда интеграция запущена в реальную работу, начинают появляться ошибки. Одни — системные, их возвращает сам API. Другие — специфичные для метода. Третьи — вообще не про API, а про то, как сформирован запрос.
По данным официальной документации, ошибки делятся на две категории: системные (возвращает REST API, могут прийти в ответ на любой метод) и методы (возвращает логика конкретного метода). Первые описаны в общем списке, вторые — на странице метода. Понимание этой разницы экономит часы диагностики.
В этой статье — 5 ошибок, которые встречаются чаще всего, и как их исправить. Если нужна разработка интеграции с обработкой ошибок — поможем.
Ошибка 1: Игнорирование системных кодов
Системные ошибки возвращает сам REST API, а не логика метода. Они могут прийти в ответ на любой запрос, и их нужно обрабатывать отдельно.
| Код | HTTP | Что значит | Что делать |
|---|---|---|---|
NO_AUTH_FOUND | 401 | Нет данных авторизации | Проверить URL вебхука или токен |
INVALID_REQUEST | 401 | Требуется HTTPS | Использовать HTTPS |
QUERY_LIMIT_EXCEEDED | 503 | Превышен лимит интенсивности | Подождать, повторить с задержкой |
OPERATION_TIME_LIMIT | 429 | Метод заблокирован по времени | Подождать, блокировка снимется автоматически |
insufficient_scope | — | Нет нужного scope | Добавить scope в вебхук или приложение |
expired_token | — | Access-токен истёк | Обменять refresh_token |
Проверяйте наличие ключа `error` в ответе, а не его значение. В некоторых случаях `error` приходит пустым, а причина — в `error_description`. Например, запрос несуществующей сделки вернёт `{"error": "", "error_description": "Not found"}`.
Ошибка 2: Неверная обработка batch
Метод `batch` позволяет упаковать до 50 вызовов в один HTTP-запрос. Но ошибки внутри пакета приходят иначе, чем в обычном ответе.
Как это работает
В успешном batch-ответе поле `result.result_error` всегда присутствует, но пустое: `"result_error": []`. Признак ошибки — записи в этом поле, а не его наличие.
Ошибка подзапроса возвращается по тому же ключу, под которым команда была передана в запросе. Например, если команда была `deal_add`, ошибка будет в `result.result_error.deal_add`.
Как исправить
- Проверять `result_error` на записи — не на наличие ключа;
- Разбирать ошибки по ключам команд — чтобы понять, какой именно подзапрос упал;
- Не прерывать весь пакет — если один подзапрос упал, остальные могли выполниться.
Ошибка 3: Заблокированный вебхук
Ошибка `INVALID_CREDENTIALS` означает, что вебхук заблокирован или не существует. Причина чаще всего — секретный код попал в публичный доступ.
Почему это происходит
- Код в публичном репозитории — GitHub, GitLab, Pastebin;
- Код в клиентском коде — JavaScript на странице;
- Вебхук удалён — владелец удалил или пересоздал;
- Владелец изменён — при редактировании вебхука администратором ключ пересоздаётся.
Как исправить
Откройте *Приложения > Разработчикам > Интеграции*, найдите вебхук, откройте *Редактировать* и скопируйте новый секретный ключ. Обновите его в своём приложении.
💡 Важно
Никогда не публикуйте URL вебхука. Если он попал в публичный доступ — считайте, что доступ к данным получили посторонние. Сразу генерируйте новый код.
Ошибка 4: BOM в теле JSON
Одна из самых коварных ошибок. API возвращает `ERROR_ARGUMENT Invalid value of parameter { $id }`, разработчик ищет проблему в параметре `id`, но причина — в BOM (Byte Order Mark) в начале тела запроса.
Что такое BOM
BOM — это последовательность байтов, которая обозначает кодировку текста. Некоторые редакторы и языки программирования добавляют её автоматически при сохранении в UTF-8. Если BOM попадает в начало JSON-тела HTTP-запроса, Битрикс24 не может корректно распарсить запрос.
Как исправить
Явно указывать кодировку UTF-8 без BOM при формировании тела запроса. Например, в 1С: `Запрос.УстановитьТелоИзСтроки(..., КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать)`.
В других языках — проверить, не добавляет ли редактор BOM, и сохранять файлы в UTF-8 без BOM.
💡 Важно
Сообщение API не всегда указывает на реальную причину. Если ошибка говорит о параметре, а параметр выглядит корректно — проверьте, как формируется тело запроса на уровне байтов.
Ошибка 5: Устаревший или неверный метод
Ошибка `ERROR_METHOD_NOT_FOUND` означает, что метода с таким именем нет. Причины: имя написано с ошибкой, метода нет в REST API, или он недоступен без нужного скоупа.
Пример
В старых версиях Битрикс24 для создания задачи использовался метод `task.item.add`. В новых версиях он устарел, актуальный — `tasks.task.add`. Если использовать старый метод, можно получить ошибку `ERROR_METHOD_NOT_FOUND` или другие ошибки, потому что метод может работать не так, как ожидается.
Как исправить
- Проверить актуальное имя метода — в документации или через `method.get`;
- Проверить скоуп — если метода нет в вебхуке, возможно, не выдан нужный scope;
- Проверить версию API — в коробочной версии REST может отставать от облачной.
Чек-лист при ошибке
Код
- Проверен ключ `error` в ответе
- Проверен `result_error` в batch
- Проверено тело запроса на BOM
- Проверено имя метода
Доступ
- Вебхук активен
- Scope выдан
- Токен не истёк
- Права пользователя проверены
Лимиты
- Не превышен лимит интенсивности
- Нет `OPERATION_TIME_LIMIT`
- batch не превышает 50 вызовов
Диагностика
- Сообщение API не принято за точный диагноз
- Проверено на уровне байтов
- Сверено с документацией метода
Наши рекомендации
Что вы получаете, заказывая разработку у нас
- Обработку ошибок — системных и методов
- Batch — с разбором `result_error`
- Безопасность вебхуков — без публикации кода
- Формирование запросов — без BOM
- Документацию — с кодами и решениями
📌 Итоговый вывод
Ошибки API — это не «сломалось». Это сигнал, который нужно правильно прочитать.
Что нужно знать:
- Системные коды: `NO_AUTH_FOUND`, `QUERY_LIMIT_EXCEEDED`, `insufficient_scope`, `expired_token`;
- Batch: ошибки в `result.result_error` по ключам команд;
- Вебхук: `INVALID_CREDENTIALS` — сгенерировать новый код;
- BOM: сообщение API может указывать не на ту причину;
- Метод: `ERROR_METHOD_NOT_FOUND` — проверить имя и scope.
Также рекомендуем: API, методы REST API, вебхуки, все статьи об API.