> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tungo.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Ошибки и ограничения

> Как устроен ответ об ошибке, по каким полям ветвиться, главные коды отказов и ограничения частоты запросов.

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

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

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "code": "platform_balance_exhausted",
    "message": "…"
  },
  "request_id": "req_…"
}
```

Поле `error.type` есть всегда, и у каждого вида свой статус HTTP. Поле `error.code` уточняет причину. Оно есть не у всех ошибок: если его нет, хватает вида и текста. Незнакомый код обрабатывайте по виду.

Поле `request_id` — номер запроса. Тот же номер приходит в заголовке `x-request-id` каждого ответа, в том числе удачного. Сохраняйте его в своём журнале: по нему запрос находится в разделе «Журнал запросов».

Если запрос не прошёл проверку полей, приходит 400 с кодом `validation_failed`. Тогда в `error.fields` перечислено, что не так с каждым полем: путь, код и текст.

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

Главное различие — пройдёт ли отказ сам. Отказ из-за частоты пройдёт: подождите и повторите. Отказ из-за денег, прав или состояния ключа не пройдёт, пока человек в кабинете что-то не изменит. Повторять такой запрос в цикле бесполезно.

| Статус | `error.code` | Что случилось | Что делать |
| - | - | - | - |
| 401 | `missing_credentials` | В запросе нет ключа | Передать заголовок `x-api-key` |
| 401 | `invalid_api_key` | Ключ неверен | Проверить, что ключ скопирован целиком |
| 401 | `key_disabled`, `key_expired`, `key_revoked` | Ключ выключен, истёк или отозван | Включить, перевыпустить или выпустить новый |
| 401 | `key_creator_lost_access` | Автор ключа больше не владелец и не администратор | Передать ключ другому человеку |
| 402 | `platform_balance_exhausted` | Баланс платформы пуст | Пополнить баланс |
| 402 | `platform_cap_reached` | Достигнут месячный потолок организации | Поднять потолок или ждать `resets_at` |
| 402 | `key_cap_reached` | Достигнут месячный потолок ключа | Поднять потолок ключа или ждать `resets_at` |
| 402 | `platform_disabled` | Платформа выключена в организации | Включить платформу |
| 403 | `missing_permission` | У ключа нет нужного права, какого — в `error.permission` | Выдать право или выпустить другой ключ |
| 403 | `ip_not_allowed` | Запрос пришёл с адреса не из списка ключа | Вызывать с разрешённого адреса или поправить список |
| 403 | `api_keys_disabled_by_policy` | Организация запретила ключи API | Обратиться к владельцу организации |
| 404 | нет | Объекта нет или он чужой | Проверить id и компании ключа |
| 409 | `turn_in_progress` | В этом чате ещё идёт предыдущий ответ | Дождаться его конца |
| 409 | `idempotency_in_progress` | Первый запрос с этим `Idempotency-Key` ещё выполняется | Подождать и повторить |
| 422 | `idempotency_key_reused` | Этот `Idempotency-Key` уже был у другого запроса | Взять новое значение |
| 429 | `rate_limited` | Слишком много запросов | Подождать столько секунд, сколько в `Retry-After` |
| 429 | `concurrent_turns_limit` | По ключу уже идёт предельное число ответов ИИ-бухгалтера | Дождаться окончания одного из них |
| 500, 503 | нет | Сбой или временная недоступность | Повторить позже |

Чужие организации, компании и документы отвечают 404, а не 403. Так API не раскрывает, что они существуют. Если компания точно есть, а запрос возвращает 404, проверьте, что она входит в компании ключа.

Статус 409 без кода на запрос к ИИ-бухгалтеру чаще всего значит, что компания не подключена к 1С. Причина написана в `error.message`. Состояние подключения показывает `GET /v1/companies/{co}/onec/status`.

Подробнее про отказы 401 и 402 написано на странице [Ключ не работает](https://docs.tungo.kz/platform/key-not-working.md). Полный список кодов есть в справочнике API, в описании ошибки.

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

Запросы по ключу считаются по минутам. Пределов два: на один ключ и на все ключи организации вместе. Действует тот, что теснее. Каждый ответ по ключу несёт три заголовка, по ним видно, сколько осталось:

* `x-ratelimit-limit` — сколько запросов можно в текущем окне.
* `x-ratelimit-remaining` — сколько из них осталось.
* `x-ratelimit-reset` — через сколько секунд начнётся новое окно.

Сверх предела приходит 429 с кодом `rate_limited` и заголовком `Retry-After` в секундах. Подождите указанное время и повторите запрос. Тот же отказ получает адрес, с которого пришло слишком много запросов с неверным ключом.

Сами пределы в этой документации не приводятся, потому что могут меняться. Действующие значения и остаток по ключу отдаёт запрос:

```sh theme={null}
curl "$TUNGO_API/v1/workspaces/$WS/platform/limits" -H "x-api-key: $TUNGO_KEY"
```

В кабинете то же показывает раздел «Пределы»: выберите ключ, и увидите, сколько у него осталось прямо сейчас.

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

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

Если вам нужно задать много вопросов сразу, ставьте их в очередь на своей стороне и держите число одновременных запросов ниже предела. В одном чате ответы идут строго по одному.

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

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

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

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

## Что дальше

* [Ключ не работает](https://docs.tungo.kz/platform/key-not-working.md): разбор отказов по одному, с действиями.
* [Баланс платформы и расход](https://docs.tungo.kz/platform/balance.md): пополнение и потолки, из-за которых приходит 402.
* [Сделать первый запрос](https://docs.tungo.kz/platform/first-request.md): заголовок `Idempotency-Key` и безопасные повторы.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.