> Dla agentów AI: instrukcja konfiguracji krok po kroku — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), indeks dokumentacji — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Błędy i limity

Limity żądań, limity czasu i kody błędów bramy. Przy każdej odpowiedzi wyjaśniamy, kiedy występuje i co zrobić: ponowić żądanie czy je poprawić.

## Limity

Liczby — z pola `limits` odpowiedzi `GET /v1/capabilities`: tam zawsze są aktualne wartości.

| Limit | Wartość | Po przekroczeniu |
| --- | --- | --- |
| Zapytania na minutę na klucz | 120, okno 60 s od pierwszego zapytania | `429 rate_limit_exceeded` i nagłówek `Retry-After`; odmowy bramy 5xx nie zużywają kwoty |
| Jednoczesne zapytania konta | ograniczone | nadmiarowe czekają w kolejce; jeśli się nie doczekają — `429 queue_timeout` |
| Rozmiar ciała zapytania | 16 MiB | `413` |
| Długość odpowiedzi | [według modeli — tabela poniżej](https://gate.joingonka.ai/pl/docs/errors#max-tokens) | powyżej pułapu modelu — przycinane do pułapu, bez błędu |
| Klucze podrzędne | do 50 na klucz zarządzający, do 120 zapytań na minutę dla każdego | podniesienie pułapów — przez support |

### Długość odpowiedzi według modeli

Bez `max_tokens` brama podstawia wartość domyślną: bez streamingu — krótszą, aby odpowiedź zmieściła się w timeoutach, w streamingu — pułap modelu. `max_completion_tokens` — to samo pole.

| `model` | Pułap | Bez streamingu | W streamingu |
| --- | ---: | ---: | ---: |
| `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 |

## Timeouty

| Etap | Wartość | Co się dzieje |
| --- | --- | --- |
| Oczekiwanie na miejsce w kolejce | 45 s | `429 queue_timeout` z nagłówkiem `Retry-After: 1` |
| Początek odpowiedzi sieci, streaming | 150 s | `504 upstream_timeout`; pobierana jest opłata za szacunkową liczbę tokenów wejściowych |
| Początek odpowiedzi sieci, bez streamingu | 150 s | `504 upstream_timeout`; pobierana jest opłata za szacunkową liczbę tokenów wejściowych |
| Generowanie odpowiedzi | ≈ 300 s | sieć przerywa generowanie: odpowiedź przychodzi z `finish_reason: length` — kontynuuj kolejnym zapytaniem |
| Pauza między chunkami streamingu | 30 s | strumień jest zamykany: `finish_reason: stop` w chunku `joingonka-stream-stalled` |
| Sygnał aktywności w streamingu | 15 s | komentarz `: keep-alive` — klienci SSE go pomijają |
| Otwarcie strumienia | 30 s | do tego momentu odmowa przychodzi kodem odpowiedzi, po nim — chunkiem `joingonka-error` |
| Wczesna odpowiedź bez streamingu | 90 s | brama zwraca `200` i co 15 s wysyła spacje — JSON pozostaje poprawny; błąd po tym przychodzi w ciele z polem `error`, status pozostaje `200` |

> **Co jest pobierane przy timeoucie**
>
> Żądania przyjętego przez sieć nie można anulować. Przy `504 upstream_timeout` pobierana jest opłata za tokeny wejściowe, za wyjściowe — nie; ponowienie to nowe obciążenie. Strumień przerwany przed końcowym `usage` jest rozliczany tak samo. Długie odpowiedzi zamawiaj z `stream: true`.

## Kody błędów

Treść błędu to obiekt `error` z polami `message, type, code, param`; nie każdy błąd ma wszystkie pola. Kieruj się statusem i `type`, doprecyzowuj po `code`: tekst `message` może się zmieniać. Format Anthropic — w sekcji [Format błędów Anthropic](https://gate.joingonka.ai/pl/docs/errors#anthropic-errors).

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

| Odpowiedź | Kiedy | Co robić |
| --- | --- | --- |
| 400 `invalid_request_error` | Nieprawidłowa treść: brak `messages`, wiadomość nie jest obiektem, treść nie jest JSON-em; nieznany model — z `param`: `model` i listą dostępnych modeli w treści | Popraw żądanie zgodnie z treścią błędu |
| 400 `invalid_request_error` `empty_content_after_normalization` | Wiadomość jest pusta po normalizacji — na przykład zawierała tylko obraz | Dodaj tekst do wiadomości |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Pluginy `web` i `privacy-sanitization` w jednym żądaniu | Zostaw jeden z nich |
| 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: odwołanie do zapisanej odpowiedzi, dialogu lub elementu; tryb w tle; wymóg wbudowanego narzędzia | Przesyłaj całą historię w `input` |
| 400 `api_error` | Sieć odrzuciła parametry — na przykład wartość `reasoning_effort` poza jej listą | Popraw wartość zgodnie z treścią błędu |
| 401 `authentication_error` | Klucz nie został znaleziony, został unieważniony lub ma nieznany format | Sprawdź klucz na stronie [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | Saldo nie wystarcza na wycenę żądania; pozostała kwota — w `balance_ngonka` | Doładuj saldo: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Żądanie bez klucza spoza strony (`is_demo: true`) | Przekaż klucz API |
| 402 `child_key_limit_exceeded` | Przekroczono limit wydatków klucza — dzienny, miesięczny lub całkowity; pozostałe kwoty — w `daily_remaining, monthly_remaining, total_remaining` | Podnieś limit klucza na stronie [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) lub poczekaj na reset |
| 403 `forbidden` | Klucz zarządzający `gm-` w żądaniu do modelu; klucz API na trasie dostępnej tylko z panelu | Do żądań używaj klucza `jg-` lub `gc-`; zarządzanie kontem — w panelu |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: modelu nie ma w katalogu lub jest tymczasowo ukryty | Weź id z `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` i inne adresy stanu, `/v1/responses/compact` | Przechowuj historię u siebie; dla Codex CLI ustaw własny id providera |
| 404 `invalid_request_error` | Nieznana ścieżka | Sprawdź metodę, ścieżkę i adres bazowy |
| 413 `invalid_request_error` | Treść żądania przekracza limit | Skróć żądanie |
| 415 `invalid_request_error` | Treść nie jest JSON-em według nagłówka: wymagany `Content-Type: application/json` | Wyślij `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Przekroczono liczbę żądań na minutę dla klucza; w treści — `rate_limit` z `limit, remaining, reset` | Poczekaj tyle sekund, ile podano w `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Model jest przeciążony w sieci Gonka | Powtórz po `Retry-After` lub weź inny model — [Modele](https://gate.joingonka.ai/pl/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Wszystkie miejsca w sieci są zajęte: kolejka jest pełna lub upłynął czas oczekiwania | Powtórz po `Retry-After` |
| 500 `server_error` | Wewnętrzny błąd bramy | Powtórz później; jeśli się powtarza — napisz do wsparcia i załącz `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: w sieci nie ma modeli embeddingowych | Skorzystaj z innej usługi embeddingów |
| 502 `api_error` `upstream_unauthorized` | Provider sieci odrzucił dane uwierzytelniające bramy — twój klucz jest w porządku | Powtórz po minucie |
| 502 `api_error` | Błąd sieci Gonka; `code` — od sieci, jeśli go przysłała | Powtórz z pauzą lub weź inny model |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Model jest obecnie niedostępny według prób sieci: awaria, uruchamianie, niestabilność lub nikt go nie obsługuje; odmowa od razu, bez oczekiwania | Weź inny model — treść błędu podpowie który; lista — [Modele](https://gate.joingonka.ai/pl/docs/models) |
| 503 `service_unavailable` | Brak dostępnych węzłów | Powtórz później |
| 504 `timeout` `upstream_timeout` | Sieć przyjęła żądanie, ale nie odpowiedziała na czas; opłata za tokeny wejściowe została pobrana | Dla długich odpowiedzi — `stream: true`; ponowienie to nowe obciążenie |

## Błędy w otwartym strumieniu

Dopóki strumień nie jest otwarty, odmowa przychodzi zwykłym kodem odpowiedzi — jak bez streamingu. Po otwarciu status to już `200`, a błąd przychodzi tak:

- Chat Completions — chunk `joingonka-error` z polem `error`, potem przerwanie bez `[DONE]`.
- Bez streamingu po wczesnej odpowiedzi — status `200` i treść z polem `error`.
- Anthropic Messages — zdarzenie `event: error`, potem strumień się zamyka.
- OpenAI Responses — zdarzenie `response.failed`, przyczyna w `response.error.code`.
- Legacy Completions — `data: {"error": …}`, potem `[DONE]`.

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

## Format błędów Anthropic

- `POST /v1/messages` odpowiada kopertą Anthropic: `{"type": "error", "error": {"type", "message"}}`.
- Odmowy bramy zachowują `type` z tabeli powyżej (`insufficient_funds`, `model_unavailable` i inne); pola `code` w tej kopercie nie ma — przyczyna jest w treści.
- Błędy formy żądania — `invalid_request_error`: brak wiadomości lub `max_tokens`, wywołanie narzędzia bez nazwy, nieznany model.
- Nieznana ścieżka — `not_found_error`, zbyt duża treść — `request_too_large`.

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

## Co powtarzać

- Po pauzie z `Retry-After`: `429`
- Z rosnącą pauzą — 1, 2, 4 s i dalej: `500`, `502`, `503 service_unavailable`, `504`
- Z innym modelem: `503 model_unavailable`
- Nie powtarzaj bez zmian — popraw żądanie, klucz lub saldo: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Każde ponowienie po `504` to nowe obciążenie wyceną wejścia; dla długich odpowiedzi włączaj `stream: true`.

Błąd się powtarza — napisz do wsparcia i załącz `x-request-id` z nagłówków odpowiedzi.