Устранение неполадок API: распространённые ошибки

Чтение 4 минОбновлено 23 окт. 2026 г.Markdown

Каждый endpoint в справочнике сегодня отмечен как Planned: это опубликованный контракт, который пока не отвечает. На этой странице перечислены ошибки, которые API будет возвращать, чтобы ваш код мог их обрабатывать с первого дня.

Сначала прочитайте ошибку #

Каждая ошибка возвращает статус 4xx или 5xx с таким же телом:

{ "error": { "code": "forbidden", "message": "…" } }

message, это простое предложение на английском, объясняющее, что пошло не так. Логируйте его, но ветвите код по code, никогда не по message.

401 unauthorized #

API не принял ваш токен. Проверьте в таком порядке:

Заголовок точно Authorization: Bearer <token>, с словом Bearer и одним пробелом.
Токен скопирован полностью. Он показывается только один раз при создании.
Токен ещё активен. В Users › API & MCP таблица Access tokens показывает срок действия и статус каждого токена, а Show revoked tokens, старые.
Если срок истёк или токен отозван, создайте новый (или Rotate его) и обновите переменную окружения.

403 forbidden #

Токен валиден, но не имеет нужного разрешения для endpoint. В справочнике у каждого endpoint указано его разрешение, например can_fan_read или can_sales_read.

Найдите разрешение в колонке Permission у endpoint.
В Users › API & MCP нажмите Edit на токене и отметьте нужное разрешение.
Вызовите GET /v1/workspace: ответ покажет, что разрешено этому токену.

Код 403 также возвращается, если токен, не являющийся токеном владельца, отправляет заголовок LanaChat-Workspace. Уберите его.

429 rate_limited #

Каждый токен может отправлять 600 запросов в минуту. В каждом ответе есть RateLimit-Remaining и RateLimit-Reset.

Подождите количество секунд из Retry-After, затем попробуйте снова.
Используйте постраничный вывод списков с limit=100, а не по одному вызову на элемент.
Отправка сообщений фанам также ограничена лимитами Telegram: смотрите Telegram accounts and pools.

Другие коды #

Status	`code`	Что делать
400	`invalid_request`	Отсутствует поле или неверный формат: `message` указывает какое
402	`insufficient_balance`	Пополните баланс перед покупкой
404	`not_found`	ID не существует в этом workspace: проверьте правильность токена
409	`conflict`	Изменение нарушает правило или `Idempotency-Key` повторно использован с другим телом
500	`server_error`	Повторите позже с тем же `Idempotency-Key`

Отправляйте Idempotency-Key при каждом POST: повторный запрос не выполнит операцию дважды. Помощник из quick start автоматически повторяет 429 и 5xx за вас.

Сбой webhook #

Доставка считается неудачной, если ваш сервер не отвечает 2xx за 10 секунд.

Отвечайте быстро. Сразу возвращайте 2xx, а медленную работу выполняйте в фоне.
Проверяйте подпись на необработанном теле, до любого JSON-парсинга. Парсенное и повторно сериализованное тело не совпадёт.
Проверьте часы сервера. Отметка времени старше 5 минут отклоняется примером кода, поэтому сбой часов приведёт к отказу всех доставок.
При вращении секрета принимайте оба значения v1.
Тестируйте с помощью POST /webhooks/{id}/test (Planned), который отправляет ping, и повторно отправляйте доставку через /deliveries/{delivery_id}/retry (Planned) после исправления.

Неудачные доставки повторяются 8 раз в течение примерно 24 часов. После 3 дней неудач endpoint приостанавливается; возобновите его через PATCH /webhooks/{id} (Planned). Одно событие может прийти дважды: игнорируйте дубликаты по id. Смотрите Webhooks.

Всё ещё проблемы? #

Откройте окно помощи внизу справа в Console и напишите команде с указанием endpoint, статуса, code и времени вызова. Никогда не вставляйте сам токен. Смотрите Get help.

Это было полезно?