Вирішення проблем з 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`	Ідентифікатор не існує в цьому workspace: перевірте, що використовуєте правильний токен
409	`conflict`	Зміна порушує правило або `Idempotency-Key` повторно використано з іншим тілом
500	`server_error`	Спробуйте пізніше з тим самим `Idempotency-Key`

Надсилайте Idempotency-Key з кожним POST: повторна спроба не виконає роботу двічі. Помічник у the 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.

Це було корисно?