> Für KI-Agenten: Schritt-für-Schritt-Anleitung zur Einrichtung — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), Dokumentationsindex — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Fehler und Limits

Anfragelimits, Timeouts und Fehlercodes des Gateways. Zu jeder Antwort steht, wann sie auftritt und was zu tun ist: Anfrage wiederholen oder korrigieren.

## Limits

Die Zahlen stammen aus dem Feld `limits` der Antwort von `GET /v1/capabilities`: dort stehen immer die aktuellen Werte.

| Limit | Wert | Bei Überschreitung |
| --- | --- | --- |
| Anfragen pro Minute pro Schlüssel | 120, Fenster 60 s ab der ersten Anfrage | `429 rate_limit_exceeded` und Header `Retry-After`; 5xx-Ablehnungen des Gateways verbrauchen kein Kontingent |
| Gleichzeitige Anfragen des Kontos | begrenzt | überzählige warten in der Warteschlange; wer nicht wartet — `429 queue_timeout` |
| Größe des Anfrage-Bodys | 16 MiB | `413` |
| Antwortlänge | [je Modell — Tabelle unten](https://gate.joingonka.ai/de/docs/errors#max-tokens) | größer als die Obergrenze des Modells — wird ohne Fehler auf die Obergrenze gekürzt |
| Untergeordnete Schlüssel | bis zu 50 pro Verwaltungsschlüssel, bis zu 120 Anfragen pro Minute für jeden | Obergrenzen anheben — über den Support |

### Antwortlänge je Modell

Ohne `max_tokens` setzt das Gateway den Standardwert ein: ohne Streaming — kürzer, damit die Antwort in die Timeouts passt, im Stream — die Obergrenze des Modells. `max_completion_tokens` — dasselbe Feld.

| `model` | Obergrenze | Ohne Streaming | Im Stream |
| --- | ---: | ---: | ---: |
| `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 |

## Timeouts

| Phase | Wert | Was passiert |
| --- | --- | --- |
| Warten auf einen Platz in der Warteschlange | 45 s | `429 queue_timeout` mit Header `Retry-After: 1` |
| Beginn der Antwort des Netzwerks, Stream | 150 s | `504 upstream_timeout`; die Schätzung der Eingabe-Tokens wird abgebucht |
| Beginn der Antwort des Netzwerks, ohne Streaming | 150 s | `504 upstream_timeout`; die Schätzung der Eingabe-Tokens wird abgebucht |
| Generierung der Antwort | ≈ 300 s | das Netzwerk bricht die Generierung ab: die Antwort kommt mit `finish_reason: length` — setzen Sie mit der nächsten Anfrage fort |
| Pause zwischen den Chunks des Streams | 30 s | der Stream wird geschlossen: `finish_reason: stop` im Chunk `joingonka-stream-stalled` |
| Aktivitätssignal im Stream | 15 s | Kommentar `: keep-alive` — SSE-Clients überspringen ihn |
| Öffnen des Streams | 30 s | bis zu diesem Moment kommt die Ablehnung als Antwortcode, danach als Chunk `joingonka-error` |
| Frühe Antwort ohne Streaming | 90 s | das Gateway liefert `200` und sendet alle 15 s Leerzeichen — das JSON bleibt gültig; ein Fehler danach kommt im Body mit dem Feld `error`, der Status bleibt `200` |

> **Was bei einem Timeout abgebucht wird**
>
> Eine vom Netzwerk angenommene Anfrage kann nicht storniert werden. Bei `504 upstream_timeout` wird die Schätzung der Eingabe-Token abgebucht, die Ausgabe-Token nicht; ein erneuter Versuch ist eine neue Abbuchung. Ein Stream, der vor dem abschließenden `usage` abbricht, wird genauso abgerechnet. Fordern Sie lange Antworten mit `stream: true` an.

## Fehlercodes

Der Fehlertext ist ein Objekt `error` mit den Feldern `message, type, code, param`; einige Felder sind nicht bei allen Fehlern vorhanden. Orientieren Sie sich am Status und `type`, prüfen Sie `code`: der Text `message` kann sich ändern. Das Anthropic-Format finden Sie im Abschnitt [Format der Anthropic-Fehler](https://gate.joingonka.ai/de/docs/errors#anthropic-errors).

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

| Antwort | Wann | Was zu tun ist |
| --- | --- | --- |
| 400 `invalid_request_error` | Ungültiger Body: kein `messages`, Nachricht ist kein Objekt, Body ist kein JSON; unbekanntes Modell — mit `param`: `model` und einer Liste verfügbarer Modelle im Text | Korrigieren Sie die Anfrage anhand des Fehlertexts |
| 400 `invalid_request_error` `empty_content_after_normalization` | Nachricht ist nach der Normalisierung leer — zum Beispiel enthielt sie nur ein Bild | Fügen Sie der Nachricht Text hinzu |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Plugins `web` und `privacy-sanitization` in einer Anfrage | Behalten Sie eines davon |
| 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: Verweis auf eine gespeicherte Antwort, einen Dialog oder ein Element; Hintergrundmodus; Anforderung eines integrierten Tools | Senden Sie den gesamten Verlauf in `input` |
| 400 `api_error` | Das Netzwerk hat die Parameter abgelehnt — zum Beispiel liegt der Wert `reasoning_effort` außerhalb seiner Liste | Korrigieren Sie den Wert anhand des Fehlertexts |
| 401 `authentication_error` | Schlüssel nicht gefunden, widerrufen oder mit unbekanntem Format | Prüfen Sie den Schlüssel auf der Seite [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | Das Guthaben reicht nicht für die Schätzung der Anfrage; der Rest steht in `balance_ngonka` | Laden Sie Ihr Guthaben auf: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Anfrage ohne Schlüssel, nicht von der Website (`is_demo: true`) | Übergeben Sie einen API-Schlüssel |
| 402 `child_key_limit_exceeded` | Das Ausgabenlimit des Schlüssels ist überschritten — täglich, monatlich oder gesamt; die Restbeträge stehen in `daily_remaining, monthly_remaining, total_remaining` | Erhöhen Sie das Limit des Schlüssels auf der Seite [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) oder warten Sie auf den Reset |
| 403 `forbidden` | Verwaltungsschlüssel `gm-` in einer Anfrage an ein Modell; API-Schlüssel auf einer nur für das Dashboard bestimmten Route | Für Anfragen — Schlüssel `jg-` oder `gc-`; Kontoverwaltung — im Dashboard |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: das Modell ist nicht im Katalog oder vorübergehend ausgeblendet | Nehmen Sie die id aus `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` und andere State-Adressen, `/v1/responses/compact` | Verwalten Sie den Verlauf selbst; für die Codex CLI legen Sie eine eigene Provider-id fest |
| 404 `invalid_request_error` | Unbekannter Pfad | Prüfen Sie Methode, Pfad und Basisadresse |
| 413 `invalid_request_error` | Der Request-Body überschreitet das Limit | Kürzen Sie die Anfrage |
| 415 `invalid_request_error` | Der Body ist laut Header kein JSON: `Content-Type: application/json` erforderlich | Senden Sie `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Die Anzahl der Anfragen pro Minute pro Schlüssel ist überschritten; im Body — `rate_limit` mit `limit, remaining, reset` | Warten Sie so viele Sekunden, wie in `Retry-After` angegeben |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Das Modell ist im Gonka-Netzwerk überlastet | Wiederholen Sie nach `Retry-After` oder nehmen Sie ein anderes Modell — [Modelle](https://gate.joingonka.ai/de/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Alle Plätze im Netzwerk sind belegt: die Warteschlange ist voll oder die Wartezeit ist abgelaufen | Wiederholen Sie nach `Retry-After` |
| 500 `server_error` | Interner Fehler des Gateways | Wiederholen Sie später; tritt es erneut auf, schreiben Sie an den Support und fügen Sie `x-request-id` bei |
| 501 `not_implemented` | `POST /v1/embeddings`: im Netzwerk gibt es keine Embedding-Modelle | Nutzen Sie einen anderen Embedding-Dienst |
| 502 `api_error` `upstream_unauthorized` | Der Provider des Netzwerks hat die Anmeldedaten des Gateways abgelehnt — Ihr Schlüssel ist in Ordnung | Wiederholen Sie in einer Minute |
| 502 `api_error` | Fehler im Gonka-Netzwerk; `code` stammt vom Netzwerk, falls es ihn gesendet hat | Wiederholen Sie mit einer Pause oder nehmen Sie ein anderes Modell |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Das Modell ist derzeit laut Netzwerk-Proben nicht verfügbar: Ausfall, Start, Instabilität oder niemand betreibt es; sofortige Ablehnung, ohne Warten | Nehmen Sie ein anderes Modell — der Fehlertext verrät welches; die Liste — [Modelle](https://gate.joingonka.ai/de/docs/models) |
| 503 `service_unavailable` | Keine verfügbaren Nodes | Wiederholen Sie später |
| 504 `timeout` `upstream_timeout` | Das Netzwerk hat die Anfrage angenommen, aber nicht rechtzeitig geantwortet; die Schätzung der Eingabe-Token wurde abgebucht | Für lange Antworten — `stream: true`; ein erneuter Versuch ist eine neue Abbuchung |

## Fehler in einem geöffneten Stream

Solange der Stream nicht geöffnet ist, kommt die Ablehnung mit dem üblichen Antwortcode — wie ohne Streaming. Nach dem Öffnen ist der Status bereits `200`, und der Fehler kommt so:

- Chat Completions — Chunk `joingonka-error` mit Feld `error`, dann Abbruch ohne `[DONE]`.
- Ohne Streaming nach einer frühen Antwort — Status `200` und Body mit Feld `error`.
- Anthropic Messages — Event `event: error`, dann wird der Stream geschlossen.
- OpenAI Responses — Event `response.failed`, Ursache in `response.error.code`.
- Legacy Completions — `data: {"error": …}`, dann `[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 der Anthropic-Fehler

- `POST /v1/messages` antwortet mit einem Anthropic-Envelope: `{"type": "error", "error": {"type", "message"}}`.
- Gateway-Ablehnungen behalten `type` aus der Tabelle oben (`insufficient_funds`, `model_unavailable` und andere); das Feld `code` gibt es in diesem Envelope nicht — die Ursache steht im Text.
- Fehler im Anfrageformat — `invalid_request_error`: keine Nachrichten oder `max_tokens`, Tool-Aufruf ohne Namen, unbekanntes Modell.
- Unbekannter Pfad — `not_found_error`, zu großer Body — `request_too_large`.

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

## Was sich wiederholen lässt

- Nach einer Pause aus `Retry-After`: `429`
- Mit wachsender Pause — 1, 2, 4 s und weiter: `500`, `502`, `503 service_unavailable`, `504`
- Mit einem anderen Modell: `503 model_unavailable`
- Nicht unverändert wiederholen — korrigieren Sie Anfrage, Schlüssel oder Guthaben: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Jede Wiederholung nach `504` ist eine neue Abbuchung der Eingabe-Schätzung; für lange Antworten aktivieren Sie `stream: true`.

Der Fehler tritt erneut auf — schreiben Sie an den Support und fügen Sie `x-request-id` aus den Antwort-Headern bei.