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

_API · Чтение 4 мин · Обновлено 2026-10-23 · https://lanachat.ai/guides/ru/api-troubleshooting/_

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

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

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

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

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

## 401 unauthorized

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

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

## 403 forbidden

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

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

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

## 429 rate_limited

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

- Подождите количество секунд из `Retry-After`, затем попробуйте снова.
- Используйте постраничный вывод списков с `limit=100`, а не по одному вызову на элемент.
- Отправка сообщений фанам также ограничена лимитами Telegram: смотрите [Telegram accounts and pools](https://lanachat.ai/guides/ru/api-telegram-accounts/).

## Другие коды

| 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](https://lanachat.ai/guides/ru/api-overview/) автоматически повторяет `429` и `5xx` за вас.

## Сбой webhook

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

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

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

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

Откройте окно помощи внизу справа в Console и напишите команде с указанием endpoint, статуса, `code` и времени вызова. Никогда не вставляйте сам токен. Смотрите [Get help](https://lanachat.ai/guides/ru/get-help/).

## Похожие статьи

- [LanaChat API: быстрое начало, аутентификация и ошибки](https://lanachat.ai/guides/ru/api-overview/)
- [API: вебхуки, события и подписи](https://lanachat.ai/guides/ru/api-webhooks/)
- [API: участники команды, роли и токены доступа](https://lanachat.ai/guides/ru/api-team/)
- [API быстрые рецепты: копируйте, вставляйте, запускайте](https://lanachat.ai/guides/ru/api-recipes/)