# Вирішення проблем з API: поширені помилки

_API · Читання 4 хв · Оновлено 2026-10-23 · https://lanachat.ai/guides/uk/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/uk/api-telegram-accounts/).

## Інші коди

| Status | `code` | Що робити |
|---|---|---|
| 400 | `invalid_request` | Відсутнє поле або неправильний формат: у `message` вказано яке |
| 402 | `insufficient_balance` | Поповніть баланс перед покупкою |
| 404 | `not_found` | Ідентифікатор не існує в цьому workspace: перевірте, що використовуєте правильний токен |
| 409 | `conflict` | Зміна порушує правило або `Idempotency-Key` повторно використано з іншим тілом |
| 500 | `server_error` | Спробуйте пізніше з тим самим `Idempotency-Key` |

Надсилайте `Idempotency-Key` з кожним `POST`: повторна спроба не виконає роботу двічі. Помічник у [the quick start](https://lanachat.ai/guides/uk/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/uk/api-webhooks/).

## Все ще не виходить?

Відкрийте допоміжний чат у правому нижньому куті Console і напишіть команді з endpoint, статусом, `code` та часом виклику. Ніколи не вставляйте сам токен. Див. [Get help](https://lanachat.ai/guides/uk/get-help/).

## Пов’язані статті

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