Перейти к основному содержанию
Любая ошибка API приходит в одном виде: статус HTTP 4xx или 5xx и JSON с видом ошибки, кодом и текстом для человека. Ветвитесь по полям error.type и error.code. Текст error.message показывайте или пишите в журнал как есть, но не разбирайте его программой: формулировки меняются.

​
Как выглядит ошибка

Поле error.type есть всегда, и у каждого вида свой статус HTTP. Поле error.code уточняет причину. Оно есть не у всех ошибок: если его нет, хватает вида и текста. Незнакомый код обрабатывайте по виду. Поле request_id — номер запроса. Тот же номер приходит в заголовке x-request-id каждого ответа, в том числе удачного. Сохраняйте его в своём журнале: по нему запрос находится в разделе «Журнал запросов». Если запрос не прошёл проверку полей, приходит 400 с кодом validation_failed. Тогда в error.fields перечислено, что не так с каждым полем: путь, код и текст.

​
Главные отказы

Главное различие — пройдёт ли отказ сам. Отказ из-за частоты пройдёт: подождите и повторите. Отказ из-за денег, прав или состояния ключа не пройдёт, пока человек в кабинете что-то не изменит. Повторять такой запрос в цикле бесполезно. Чужие организации, компании и документы отвечают 404, а не 403. Так API не раскрывает, что они существуют. Если компания точно есть, а запрос возвращает 404, проверьте, что она входит в компании ключа. Статус 409 без кода на запрос к ИИ-бухгалтеру чаще всего значит, что компания не подключена к 1С. Причина написана в error.message. Состояние подключения показывает GET /v1/companies/{co}/onec/status. Подробнее про отказы 401 и 402 написано на странице Ключ не работает. Полный список кодов есть в справочнике API, в описании ошибки.

​
Частота запросов

Запросы по ключу считаются по минутам. Пределов два: на один ключ и на все ключи организации вместе. Действует тот, что теснее. Каждый ответ по ключу несёт три заголовка, по ним видно, сколько осталось:
  • x-ratelimit-limit — сколько запросов можно в текущем окне.
  • x-ratelimit-remaining — сколько из них осталось.
  • x-ratelimit-reset — через сколько секунд начнётся новое окно.
Сверх предела приходит 429 с кодом rate_limited и заголовком Retry-After в секундах. Подождите указанное время и повторите запрос. Тот же отказ получает адрес, с которого пришло слишком много запросов с неверным ключом. Сами пределы в этой документации не приводятся, потому что могут меняться. Действующие значения и остаток по ключу отдаёт запрос:
В кабинете то же показывает раздел «Пределы»: выберите ключ, и увидите, сколько у него осталось прямо сейчас.

​
Одновременные запросы к ИИ-бухгалтеру

По одному ключу одновременно может идти ограниченное число ответов ИИ-бухгалтера. Это отдельное ограничение, оно не связано с частотой. Запрос сверх него получает 429 с кодом concurrent_turns_limit и заголовком Retry-After. Текущий предел и число занятых мест лежат в ответе того же запроса пределов, в поле concurrent_turns. Если вам нужно задать много вопросов сразу, ставьте их в очередь на своей стороне и держите число одновременных запросов ниже предела. В одном чате ответы идут строго по одному.

​
Размеры запросов

Вопрос ИИ-бухгалтеру принимается длиной до 4000 знаков. К вопросу можно приложить файлы. Сколько файлов и какого размера допустимо, а также наибольший размер тела запроса отдаёт тот же запрос пределов, в поле files. Слишком большой запрос получает 413 с кодом payload_too_large.

​
Вызовы из браузера

API не поддерживает запросы из кода страницы в браузере, то есть CORS. Ключ является секретом, а в браузере его увидит любой посетитель. Предварительный запрос OPTIONS к адресам /v1 отвечает 403 с кодом cors_not_supported. Вызывайте API со своего сервера, а странице отдавайте уже готовый результат.

​
Что дальше