error.code. Ниже коды собраны по статусам. Быстрее всего проверить ключ запросом о нём самом:
blocked_reason: в нём код того отказа, который сейчас получит запрос к ИИ-бухгалтеру, или null, если всё в порядке. В кабинете то же написано под заголовком «Сейчас ключ не сработает»: Платформа → Ключи API, меню ключа, пункт Подробнее и расход.
Почти всё на этой странице исправляет владелец или администратор организации в кабинете. По самому ключу ни ключи, ни баланс поменять нельзя.
Ключ не принят: 401
missing_credentials
Запрос пришёл без ключа. Проверьте, что заголовок называется x-api-key и переменная с ключом не пуста. Подойдёт и заголовок Authorization: Bearer tg_…. Если запрос отправляет код страницы в браузере, дело в другом: см. cors_not_supported ниже.
invalid_api_key
Такого ключа нет. Обычно ключ скопирован не целиком или с лишним пробелом и переводом строки. Ключ начинается с tg_, сверьте его начало со столбцом «Ключ» в списке ключей. Целиком ключ посмотреть уже нельзя: если он потерян, перевыпустите его.
key_disabled
Ключ выключили в кабинете. Включить его может автор ключа или владелец организации: меню ключа, пункт Включить. Секрет при этом остаётся прежним, в программе ничего менять не нужно.
key_expired
У ключа закончился срок. Продлить истёкший ключ нельзя. Автор ключа может его перевыпустить: меню ключа, пункт Перевыпустить. Права, компании и потолок сохранятся, срок начнётся заново, но секрет будет новый, и его нужно заменить в программе. Если автора нет, выпустите новый ключ.
key_revoked
Ключ отозван, вернуть его нельзя. Выпустите новый ключ с теми же правами и замените его в программе.
key_creator_lost_access
Ключ действует от имени того, кто его выпустил. Этот человек больше не владелец и не администратор организации, поэтому ключ остановлен. Владелец организации может передать ключ другому владельцу или администратору: меню ключа, пункт Передать. Секрет и срок при передаче не меняются.
Ключ принят, но запрос к ИИ-бухгалтеру отклонён: 402
Отказ 402 значит, что нужны деньги или решение человека. Ждать и повторять бесполезно, кроме случаев, когда в ошибке есть полеresets_at.
platform_balance_exhausted
Баланс платформы пуст. Пополните его: Платформа → Баланс и оплата, кнопка Пополнить. Если включено автопополнение, оно уже запущено, и запрос можно повторить чуть позже. Подробности на странице Баланс платформы и расход.
platform_cap_reached
Траты организации дошли до месячного потолка. Потолок обнулится сам в момент из поля resets_at, это начало следующего месяца по времени Алматы. Чтобы продолжить раньше, поднимите «Потолок трат за месяц» на странице «Баланс и оплата».
key_cap_reached
Этот ключ дошёл до своего месячного потолка, или остаток потолка меньше оценки одного вызова модели. Остальные ключи организации продолжают работать. Поднять потолок ключа может его автор: меню ключа, пункт Изменить. Иначе ключ заработает в момент из resets_at.
platform_disabled
Платформа выключена в организации, поэтому остановлены все ключи и автоматизации. Включите переключатель «Платформа включена» на странице «Баланс и оплата».
Ключу нельзя: 403
missing_permission
У ключа нет права на это действие. Какого именно, сказано в поле error.permission, например chat.use. Автор ключа может добавить право через «Изменить», если оно есть у него самого в этой компании. Иначе выпустите другой ключ.
ip_not_allowed
У ключа задан список разрешённых адресов, а запрос пришёл с другого. Вызывайте API с разрешённого адреса или добавьте новый в поле «Разрешённые адреса». Добавить адрес может только автор ключа.
api_keys_disabled_by_policy
Организация запретила ключи API целиком, поэтому не работает ни один ключ. Настройку «Разрешить ключи API» включает владелец организации в её настройках.
webhooks_require_all_companies
Вебхуками управляет только ключ на все компании организации, потому что события приходят по всем компаниям. Выпустите для этого отдельный ключ на все компании с правом webhooks.manage или добавляйте адреса в кабинете.
cors_not_supported
Запрос отправлен из кода страницы в браузере. API так не вызывается: ключ является секретом и должен оставаться на сервере. Перенесите вызов на свой сервер.
Ключ работает, но запросы возвращают 404 или 409
404 на компанию, которая точно есть
Чужие и недоступные компании отвечают так же, как несуществующие. Проверьте список компаний ключа запросомGET /v1/companies. Ключ на все компании видит только те, где состоит его автор: если компанию завели недавно, автора нужно добавить в неё.
409 на вопрос ИИ-бухгалтеру
Чаще всего компания не подключена к 1С, причина написана вerror.message. Состояние подключения показывает GET /v1/companies/{co}/onec/status. Как подключить 1С, описано в разделе Подключение 1С. Код turn_in_progress значит другое: в этом чате ещё идёт предыдущий ответ.
Слишком часто: 429
rate_limited
Запросов больше, чем разрешено в минуту на ключ или на все ключи организации. Подождите столько секунд, сколько указано в заголовке Retry-After, и повторите. Тот же отказ приходит, если с вашего адреса было много запросов с неверным ключом: сначала исправьте ключ.
concurrent_turns_limit
По ключу уже идёт предельное число ответов ИИ-бухгалтера одновременно. Дождитесь окончания одного из них. Если вопросов много, ставьте их в очередь на своей стороне.
Что дальше
- Ошибки и ограничения: общий вид ошибки и заголовки частоты запросов.
- Создать ключ API: права, срок, перевыпуск и передача ключа.
- Баланс платформы и расход: пополнение и потолки.