> Для ИИ-агентов: пошаговая инструкция по настройке — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), индекс документации — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Ошибки и лимиты

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

## Лимиты

Числа — из поля `limits` ответа `GET /v1/capabilities`: там всегда актуальные значения.

| Лимит | Значение | При превышении |
| --- | --- | --- |
| Запросов в минуту на ключ | 120, окно 60 с от первого запроса | `429 rate_limit_exceeded` и заголовок `Retry-After`; отказы шлюза 5xx квоту не тратят |
| Одновременные запросы аккаунта | ограничены | лишние ждут в очереди; не дождались — `429 queue_timeout` |
| Размер тела запроса | 16 МиБ | `413` |
| Длина ответа | [по моделям — таблица ниже](https://gate.joingonka.ai/ru/docs/errors#max-tokens) | больше потолка модели — срезается до потолка, без ошибки |
| Дочерние ключи | до 50 на управляющий ключ, до 120 запросов в минуту каждому | поднять потолки — через поддержку |

### Длина ответа по моделям

Без `max_tokens` шлюз подставляет умолчание: без стрима — короче, чтобы ответ уложился в таймауты, в стриме — потолок модели. `max_completion_tokens` — то же поле.

| `model` | Потолок | Без стрима | В стриме |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | 8192 | 1500 | 8192 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | 32768 | 1500 | 32768 |
| `zai-org/GLM-5.3-Flash` | 8192 | 3000 | 8192 |

## Таймауты

| Этап | Значение | Что происходит |
| --- | --- | --- |
| Ожидание места в очереди | 45 с | `429 queue_timeout` с заголовком `Retry-After: 1` |
| Начало ответа сети, стрим | 150 с | `504 upstream_timeout`; списывается оценка входных токенов |
| Начало ответа сети, без стрима | 150 с | `504 upstream_timeout`; списывается оценка входных токенов |
| Генерация ответа | ≈ 300 с | сеть обрывает генерацию: ответ приходит с `finish_reason: length` — продолжите следующим запросом |
| Пауза между чанками стрима | 30 с | поток закрывается: `finish_reason: stop` в чанке `joingonka-stream-stalled` |
| Сигнал активности в стриме | 15 с | комментарий `: keep-alive` — SSE-клиенты его пропускают |
| Открытие потока | 30 с | до этого момента отказ приходит кодом ответа, после — чанком `joingonka-error` |
| Ранний ответ без стрима | 90 с | шлюз отдаёт `200` и каждые 15 с шлёт пробелы — JSON остаётся валидным; ошибка после этого приходит телом с полем `error`, статус остаётся `200` |

> **Что списывается при таймауте**
>
> Принятый сетью запрос отменить нельзя. При `504 upstream_timeout` списывается оценка входных токенов, выходные — нет; повтор — новое списание. Стрим, оборванный до итогового `usage`, оплачивается так же. Длинные ответы просите с `stream: true`.

## Коды ошибок

Тело ошибки — объект `error` с полями `message, type, code, param`; часть полей есть не у всех ошибок. Ориентируйтесь на статус и `type`, уточняйте по `code`: текст `message` может меняться. Формат Anthropic — в разделе [Формат ошибок Anthropic](https://gate.joingonka.ai/ru/docs/errors#anthropic-errors).

```json
{
  "error": {
    "message": "Model is currently overloaded in the Gonka network",
    "type": "rate_limit_exceeded",
    "code": "upstream_rate_limited"
  }
}
```

| Ответ | Когда | Что делать |
| --- | --- | --- |
| 400 `invalid_request_error` | Неверное тело: нет `messages`, сообщение не объект, тело не JSON; неизвестная модель — с `param`: `model` и списком доступных моделей в тексте | Исправьте запрос по тексту ошибки |
| 400 `invalid_request_error` `empty_content_after_normalization` | Сообщение пустое после нормализации — например, в нём была только картинка | Добавьте в сообщение текст |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Плагины `web` и `privacy-sanitization` в одном запросе | Оставьте один из них |
| 400 `invalid_request_error` `previous_response_id_not_supported` `conversation_not_supported` `item_reference_not_supported` `background_not_supported` `hosted_tool_choice_not_supported` | OpenAI Responses: ссылка на сохранённый ответ, диалог или элемент; фоновый режим; требование встроенного инструмента | Присылайте историю целиком в `input` |
| 400 `api_error` | Сеть отклонила параметры — например, значение `reasoning_effort` вне её списка | Исправьте значение по тексту ошибки |
| 401 `authentication_error` | Ключ не найден, отозван или неизвестного формата | Проверьте ключ на странице [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | Баланса не хватает на оценку запроса; остаток — в `balance_ngonka` | Пополните баланс: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Запрос без ключа не с сайта (`is_demo: true`) | Передайте API-ключ |
| 402 `child_key_limit_exceeded` | Превышен лимит расходов ключа — дневной, месячный или общий; остатки — в `daily_remaining, monthly_remaining, total_remaining` | Поднимите лимит ключа на странице [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) или дождитесь сброса |
| 403 `forbidden` | Управляющий ключ `gm-` в запросе к модели; API-ключ на маршруте только для кабинета | Для запросов — ключ `jg-` или `gc-`; управление аккаунтом — в кабинете |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: модели нет в каталоге или она временно скрыта | Возьмите id из `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` и другие адреса состояния, `/v1/responses/compact` | Храните историю у себя; для Codex CLI задайте свой id провайдера |
| 404 `invalid_request_error` | Неизвестный путь | Проверьте метод, путь и базовый адрес |
| 413 `invalid_request_error` | Тело запроса больше лимита | Сократите запрос |
| 415 `invalid_request_error` | Тело не JSON по заголовку: нужен `Content-Type: application/json` | Отправьте `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Превышено число запросов в минуту на ключ; в теле — `rate_limit` с `limit, remaining, reset` | Подождите столько секунд, сколько в `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Модель перегружена в сети Gonka | Повторите после `Retry-After` или возьмите другую модель — [Модели](https://gate.joingonka.ai/ru/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Все места к сети заняты: очередь полна или ожидание истекло | Повторите после `Retry-After` |
| 500 `server_error` | Внутренняя ошибка шлюза | Повторите позже; повторяется — напишите в поддержку и приложите `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: в сети нет эмбеддинговых моделей | Возьмите другой сервис эмбеддингов |
| 502 `api_error` `upstream_unauthorized` | Провайдер сети отклонил учётные данные шлюза — ваш ключ в порядке | Повторите через минуту |
| 502 `api_error` | Ошибка сети Gonka; `code` — от сети, если она его прислала | Повторите с паузой или возьмите другую модель |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Модель сейчас недоступна по пробам сети: сбой, запуск, нестабильность или её никто не обслуживает; отказ сразу, без ожидания | Возьмите другую модель — текст ошибки подскажет какую; список — [Модели](https://gate.joingonka.ai/ru/docs/models) |
| 503 `service_unavailable` | Нет доступных нод | Повторите позже |
| 504 `timeout` `upstream_timeout` | Сеть приняла запрос, но не ответила вовремя; оценка входных токенов списана | Для длинных ответов — `stream: true`; повтор — новое списание |

## Ошибки в открытом потоке

Пока поток не открыт, отказ приходит обычным кодом ответа — как без стрима. После открытия статус уже `200`, и ошибка приходит так:

- Chat Completions — чанк `joingonka-error` с полем `error`, затем обрыв без `[DONE]`.
- Без стрима после раннего ответа — статус `200` и тело с полем `error`.
- Anthropic Messages — событие `event: error`, затем поток закрывается.
- OpenAI Responses — событие `response.failed`, причина в `response.error.code`.
- Legacy Completions — `data: {"error": …}`, затем `[DONE]`.

```text
data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}
```

## Формат ошибок Anthropic

- `POST /v1/messages` отвечает конвертом Anthropic: `{"type": "error", "error": {"type", "message"}}`.
- Отказы шлюза сохраняют `type` из таблицы выше (`insufficient_funds`, `model_unavailable` и другие); поля `code` в этом конверте нет — причина в тексте.
- Ошибки формы запроса — `invalid_request_error`: нет сообщений или `max_tokens`, вызов инструмента без имени, неизвестная модель.
- Неизвестный путь — `not_found_error`, слишком большое тело — `request_too_large`.

```text
event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}
```

## Что повторять

- После паузы из `Retry-After`: `429`
- С нарастающей паузой — 1, 2, 4 с и дальше: `500`, `502`, `503 service_unavailable`, `504`
- С другой моделью: `503 model_unavailable`
- Не повторять без изменений — исправьте запрос, ключ или баланс: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Каждый повтор после `504` — новое списание оценки входа; для длинных ответов включайте `stream: true`.

Ошибка повторяется — напишите в поддержку и приложите `x-request-id` из заголовков ответа.