Ошибка получения токена авторизации Битрикс24

Авторизация приложения Битрикс24 устроена так: приложение получает access-токен на короткий срок и refresh-токен для продления. Пока продление проходит, интеграция живёт; как только цепочка рвётся, начинаются ошибки. Разбирать их надо по коду в поле error, а не по тексту — текст меняется и приходит на языке интерфейса.

Ошибки сервера авторизации

Их возвращает oauth.bitrix24.tech при обмене кода на токены и при продлении.

• invalid_request — запрос составлен неверно. Проверьте набор и написание параметров.
• invalid_client — неверные данные клиента или приложение не установлено в этом портале. Сверьте client_id и client_secret, проверьте установку.
• insufficient_scope или invalid_scope — запрошены права, которых нет в карточке приложения. Права добавляют в карточку, а не в запрос.
• invalid_grant — авторизационные данные некорректны. Приходит и при первом получении токенов, и при продлении. Если истёк refresh-токен, помогает только повторная авторизация по полному протоколу.
• PAYMENT_REQUIRED — закончился пробный или оплаченный период приложения. Пока не продлена оплата, токены не выдаются.

Ошибки при вызове методов

Эти приходят уже от самого REST API, в ответ на любой метод:

• expired_token (401) — срок access-токена истёк. Продлите токены и повторите вызов.
• NO_AUTH_FOUND (401) — в запросе нет ни токена, ни кода вебхука.
• user_access_error (401) — приложение установлено, но администратор открыл к нему доступ только части сотрудников.
• insufficient_scope (401) — запрос требует прав шире выданных. У приложения текст заканчивается на provided by the access token, у вебхука — на provided by the webhook token.
• ACCESS_DENIED (401) — REST доступен только на коммерческих тарифах.
• INVALID_REQUEST, Https required (401) — методы вызываются только по https.

Код может встретиться и в системном перечне, и в перечне метода — различает их HTTP-статус. Системные ошибки авторизации приходят с 401, ошибки метода — с 400 или 403.

Почему интеграция отваливается через месяц

Чаще всего интеграция написана «на вечный токен»: сохранённые значения лежат в файле, продления нет. Работает она до первого истечения срока. Второй вариант: продление написано, но интеграция месяц никто не вызывал, за это время истёк и refresh-токен — остаётся авторизоваться заново руками.

Продление токенов — часть интеграции, а не необязательное дополнение. И если задача целиком внутри одного портала, проще взять вебхук: у него постоянный код.

Коротко: что проверить

1. Код в поле error и HTTP-статус ответа.
2. Установлено ли приложение в портале и те ли client_id с client_secret.
3. Права в карточке приложения против прав, нужных методу.
4. Реализовано ли продление токенов и когда оно проходило последний раз.
5. Оплату приложения и тариф портала.

С чего начинать работу с REST — в материале про REST API Битрикс24.

Проверяли по первоисточнику: документация REST API Битрикс24