Коды ошибок
Машинно-читаемые коды, которые приходят в поле error.code ответа. Используйте их как стабильный признак для логики, а не текст сообщения. Best practices §1 описывает, как обработать 429 и 5xx.
| Код | HTTP | Когда возникает | Что делать |
|---|---|---|---|
| MISSING_API_KEY | 401 | В запросе нет заголовка Authorization или он пустой. | Добавьте заголовок Authorization: Bearer btx_live_… Проверьте, что прокси не вырезает заголовок. |
| INVALID_API_KEY | 401 | Ключ не существует, повреждён, или подпись/префикс не совпадают. | Сверьте ключ с тем, что в /developers. Если ключ корректен — возможно, он был отозван SA. |
| KEY_REVOKED | 401 | Ключ существовал, но был отозван владельцем проекта или SA. | Выпустите новый ключ в кабинете /developers и обновите интеграции. Старый ключ восстановить нельзя. |
| INSUFFICIENT_SCOPE | 403 | Ключ существует, но у него нет нужного scope для этого endpoint. | Создайте новый ключ с дополнительным scope (например, messages:send) — изменить scopes у существующего нельзя. |
| API_NOT_AVAILABLE_ON_PLAN | 403 | Тариф проекта не включает публичный API. | Повысьте тариф в /billing до уровня, где включён публичный API. |
| TRIAL_READ_ONLY | 403 | Проект на триале — мутирующие методы (POST/PUT/DELETE) запрещены. | Перейдите на платный тариф, или используйте только GET-эндпоинты для ознакомления. |
| RATE_LIMIT_EXCEEDED | 429 | Превышен лимит запросов в минуту или сутки для текущего тарифа. | Подождите Retry-After секунд и повторите. Реализуйте exponential backoff (см. Best Practices §1). |
| NO_CHANNEL_AVAILABLE | 422 | POST /messages: контакт не имеет last_channel, и channel не передан в payload. | Передайте параметр channel явно (telegram | widget | vk) или дождитесь первого входящего сообщения от контакта. |
| CHANNEL_NOT_SUPPORTED_YET | 422 | Канал есть в системе как тип, но интеграция в публичный API ещё не подключена. | Используйте поддерживаемые каналы (telegram, widget, vk). Список — в GET /public/v1/channels. |
| CHANNEL_NOT_CONNECTED | 422 | Указанный канал не подключён в этом проекте (например, в проект не привязан Telegram-бот). | Подключите канал в кабинете → Каналы, либо отправляйте через другой канал. |
| CONTACT_NOT_REACHABLE | 422 | У контакта нет идентификатора для выбранного канала (нет chat_id для telegram, нет phone для whatsapp). | Используйте канал, в котором контакт когда-то писал боту (см. last_channel), либо подтяните недостающие данные через PUT /contacts/{id}. |
| DELIVERY_FAILED | 502 | Канал (Telegram/WhatsApp/VK) отверг отправку — заблокированный получатель, недоступная сеть и т.д. | Проверьте ответ, повторите через retry с экспоненциальным backoff. Если ошибка постоянная — контакт заблокировал бота. |
| SCENARIO_INACTIVE | 422 | Запуск /scenarios/{id}/run для сценария, который выключен в кабинете или удалён. | Активируйте сценарий в Bot-tree, либо запустите другой активный сценарий. |
| CONTACT_NOT_FOUND | 422 | Контакт с указанным id не существует или принадлежит другому проекту. | Проверьте contact_id. Public API запрещает доступ к контактам из чужих проектов — это не ошибка интеграции. |
| CONTACT_BUSY | 422 | POST /scenarios/{id}/run: контакт уже находится в активном диалоге другого сценария. | Передайте force=true в payload, чтобы прервать предыдущий диалог. Без force предыдущий контекст не теряется. |
| NO_START_BLOCK | 422 | Запуск сценария, в котором нет стартового блока (Bot-tree пустой или некорректный). | Откройте сценарий в Bot-tree и добавьте стартовый блок. Это ошибка конфигурации, не клиента. |