Каталог ошибок
Все ошибки приходят в формате application/problem+json (RFC 9457). Ветвите логику по полю code, а не по тексту detail. Поле type каждой ошибки ведёт на эту страницу.
Доступ и ключ
| Код | HTTP | Название | Когда приходит | Что делать |
|---|---|---|---|---|
integration_inactive | 401 | Integration is not active | Интеграция приостановлена или отозвана, либо её владелец потерял доступ. Ключ верный, дело не в нём. | Проверьте интеграцию в кабинете (Настройки → API). |
invalid_api_key | 401 | Invalid API key | Заголовка нет, ключ не найден, отозван или истёк. Ответ намеренно одинаков во всех случаях: платформа не подтверждает, что такой ключ существовал. | Проверьте ключ; срок действия виден в GET /me (key.expires_at). При необходимости выпустите новый. Автоматически не повторяйте. |
wrong_cell | 401 | Key belongs to another cell | Ключ выпущен в другой ячейке. В ответе есть поле correct_base_url. | Используйте базовый адрес из correct_base_url. |
feature_not_in_plan | 403 | API is not included in the plan | Лицензия или тариф не включают API (api_access) либо конкретную возможность. | Смените тариф или обратитесь в поддержку. |
ip_not_allowed | 403 | IP address is not allowed | Запрос пришёл с адреса вне списка интеграции. | Добавьте адрес в список или вызывайте с разрешённого. |
pii_transfer_not_allowed | 403 | Personal data transfer is not allowed | Ячейка RU: запрошена область с персональными данными, а список IP или страна размещения принимающей системы не разрешают передачу. | Разместите принимающую систему в РФ, задайте список IP либо не запрашивайте области с ПДн. |
scope_missing | 403 | Scope is missing | Нет нужной области, либо она срезана ролью интеграции, правами владельца или тарифом. | Проверьте области в GET /me (key.scopes) и права владельца. |
tenant_inactive | 403 | Account is not active | Учётная запись арендатора не активна. | Обратитесь в поддержку. |
Запрос
| Код | HTTP | Название | Когда приходит | Что делать |
|---|---|---|---|---|
bad_request | 400 | Bad request | Тело запроса не JSON либо неверный Content-Type или заголовок. | Исправьте запрос; повтор без изменений бессмыслен. |
idempotency_key_required | 400 | Idempotency-Key header is required | Для этого запроса обязателен заголовок Idempotency-Key. | Добавьте заголовок со значением, уникальным для операции. |
not_found | 404 | Not found | Ресурса нет либо он принадлежит другому арендатору (для клиента это одно и то же). | Проверьте идентификатор. |
method_not_allowed | 405 | Method not allowed | Метод не поддерживается этим адресом. | Проверьте справочник. |
channel_not_configured | 409 | Integration channel is not configured | У интеграции нет канала api: заводить диалоги и принимать сообщения клиентов некуда. Канал подключается в кабинете (Настройки → API → «Подключить канал чата»). | Подключите канал в кабинете; channel_id виден в GET /me. Повтор без этого бессмыслен. |
encryption_key_required | 409 | Encryption key is required | Интеграция настроена выдавать поля с персональными данными только в формате JWE (режим required), а открытый ключ получателя не зарегистрирован. Бывает только на ячейках EN и ID. | Зарегистрируйте свой открытый ключ (PUT /me/encryption-key или кабинет) либо запросите поля без персональных данных через fields=. |
idempotency_conflict | 409 | Idempotency key was used with a different request | Idempotency-Key уже использован с другим телом запроса. | Для нового запроса используйте новый ключ либо повторите прежний запрос. |
invalid_state | 409 | Invalid state | Действие недопустимо в текущем состоянии ресурса. | Перечитайте ресурс и проверьте его состояние. |
operation_in_progress | 409 | Operation is in progress | Параллельный повтор: операция с этим Idempotency-Key ещё выполняется. | Подождите Retry-After либо опросите операцию. |
precondition_failed | 412 | Precondition failed | If-Match не совпал с текущей версией ресурса: его изменили. | Перечитайте ресурс и примените правку к актуальной версии. |
payload_too_large | 413 | Payload too large | Тело запроса больше 256 КБ. | Уменьшите тело. |
validation_failed | 422 | Validation failed | Параметры не прошли проверку; подробности в errors[]. | Исправьте запрос по errors[]. |
precondition_required | 428 | Precondition required | Для изменения не передан If-Match. | Передайте версию из последнего чтения. |
Деньги и пределы
| Код | HTTP | Название | Когда приходит | Что делать |
|---|---|---|---|---|
insufficient_funds | 402 | Insufficient funds | На кошельке недостаточно средств для платной операции. | Пополните кошелёк. |
spend_limit_reached | 402 | Spend limit reached | Достигнут суточный предел трат интеграции (сутки по часовому поясу ячейки) либо оценка стоимости операции выше максимума одной операции (по умолчанию 100 в валюте кошелька). Предел одновременных операций — отдельный код concurrency_limit (429). | Дождитесь следующих суток или повысьте предел; для максимума операции — выберите агенту модель дешевле или уменьшите max_tokens. Предел и траты — GET /me (wallet.daily_spend, limits.max_operation_cost). |
wallet_suspended | 402 | Wallet is suspended | Обмен остановлен: баланс кошелька арендателя отрицателен или кошелёк заблокирован. Отвечают 402 все маршруты, кроме GET /me и GET /wallet; входящие данные (события, сообщения, лиды) не принимаются, исходящие вебхуки откладываются. В ответе есть topup_url и balance. | Пополните кошелёк по topup_url (нужен вход сотрудника с правом пополнения). Обмен возобновится сам в течение 30 секунд после зачисления; состояние видно в GET /wallet. События не теряются: вебхуки доставятся после пополнения. |
concurrency_limit | 429 | Too many concurrent operations | У интеграции уже выполняется наибольшее число одновременных платных операций (по умолчанию 5, значение — GET /me, limits.paid_concurrency). | Подождите Retry-After или завершения текущих операций и повторите с тем же Idempotency-Key. Ставьте реплики в очередь у себя. |
rate_limited | 429 | Too many requests | Превышен предел частоты запросов. | Подождите Retry-After секунд и повторите с тем же Idempotency-Key. |
Платформа
| Код | HTTP | Название | Когда приходит | Что делать |
|---|---|---|---|---|
internal_error | 500 | Internal error | Внутренняя ошибка платформы. Подробности в ответе не раскрываются. | Повторите с паузой; при повторении сообщите request_id в поддержку. |
service_unavailable | 503 | Service unavailable | Хранилище пределов или база недоступны, либо API не включён на ячейке: безопасно принять запись нельзя. | Повторите с паузой и тем же Idempotency-Key. |
upstream_unavailable | 503 | Upstream service unavailable | Недоступна внешняя зависимость, например языковая модель. | Повторите с паузой и тем же Idempotency-Key. |