> Для ШІ-агентів: покрокова інструкція з налаштування — [`/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/uk/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/uk/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/uk/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/uk/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` із заголовків відповіді.