> Per gli agenti AI: guida passo passo alla configurazione — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), indice della documentazione — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Errori e limiti

Limiti di richieste, timeout e codici di errore del gateway. Per ogni risposta è indicato quando si verifica e cosa fare: ripetere la richiesta o correggerla.

## Limiti

I numeri provengono dal campo `limits` della risposta `GET /v1/capabilities`: lì i valori sono sempre aggiornati.

| Limite | Valore | In caso di superamento |
| --- | --- | --- |
| Richieste al minuto per chiave | 120, finestra di 60 s dalla prima richiesta | `429 rate_limit_exceeded` e header `Retry-After`; i rifiuti 5xx del gateway non consumano la quota |
| Richieste simultanee dell'account | limitate | quelle in eccesso attendono in coda; se non arrivano in tempo — `429 queue_timeout` |
| Dimensione del body della richiesta | 16 MiB | `413` |
| Lunghezza della risposta | [per modello — tabella qui sotto](https://gate.joingonka.ai/it/docs/errors#max-tokens) | oltre il tetto del modello — viene tagliata al tetto, senza errore |
| Chiavi figlie | fino a 50 per chiave di gestione, fino a 120 richieste al minuto ciascuna | per alzare i tetti — tramite l'assistenza |

### Lunghezza della risposta per modello

Senza `max_tokens` il gateway applica il valore predefinito: senza streaming — più corto, così la risposta rientra nei timeout; nello streaming — il tetto del modello. `max_completion_tokens` — lo stesso campo.

| `model` | Tetto | Senza streaming | Nello streaming |
| --- | ---: | ---: | ---: |
| `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 |

## Timeout

| Fase | Valore | Cosa succede |
| --- | --- | --- |
| Attesa di un posto in coda | 45 s | `429 queue_timeout` con header `Retry-After: 1` |
| Inizio della risposta della rete, streaming | 150 s | `504 upstream_timeout`; viene addebitata la stima dei token di input |
| Inizio della risposta della rete, senza streaming | 150 s | `504 upstream_timeout`; viene addebitata la stima dei token di input |
| Generazione della risposta | ≈ 300 s | la rete interrompe la generazione: la risposta arriva con `finish_reason: length` — continua con la richiesta successiva |
| Pausa tra i chunk dello streaming | 30 s | il flusso viene chiuso: `finish_reason: stop` nel chunk `joingonka-stream-stalled` |
| Segnale di attività nello streaming | 15 s | commento `: keep-alive` — i client SSE lo ignorano |
| Apertura del flusso | 30 s | fino a questo momento il rifiuto arriva con un codice di risposta, dopo — con il chunk `joingonka-error` |
| Risposta anticipata senza streaming | 90 s | il gateway invia `200` e ogni 15 s manda spazi — il JSON resta valido; un errore successivo arriva nel body con il campo `error`, lo stato resta `200` |

> **Cosa viene addebitato in caso di timeout**
>
> Una richiesta accettata dalla rete non può essere annullata. Con `504 upstream_timeout` viene addebitata la stima dei token di input, mentre i token di output no; un nuovo tentativo comporta un nuovo addebito. Anche uno stream interrotto prima del `usage` finale viene fatturato allo stesso modo. Per le risposte lunghe richiedi `stream: true`.

## Codici di errore

Il corpo dell'errore è un oggetto `error` con i campi `message, type, code, param`; alcuni campi non sono presenti in tutti gli errori. Fai riferimento allo stato e a `type`, verifica con `code`: il testo di `message` può cambiare. Il formato Anthropic è nella sezione [Formato degli errori Anthropic](https://gate.joingonka.ai/it/docs/errors#anthropic-errors).

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

| Risposta | Quando | Cosa fare |
| --- | --- | --- |
| 400 `invalid_request_error` | Corpo non valido: manca `messages`, il messaggio non è un oggetto, il corpo non è JSON; modello sconosciuto — con `param`: `model` e l'elenco dei modelli disponibili nel testo | Correggi la richiesta seguendo il testo dell'errore |
| 400 `invalid_request_error` `empty_content_after_normalization` | Messaggio vuoto dopo la normalizzazione — ad esempio conteneva solo un'immagine | Aggiungi del testo al messaggio |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Plugin `web` e `privacy-sanitization` nella stessa richiesta | Lascia solo uno dei due |
| 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: riferimento a una risposta salvata, a una conversazione o a un elemento; modalità in background; richiesta di uno strumento integrato | Invia l'intera cronologia in `input` |
| 400 `api_error` | La rete ha rifiutato i parametri — ad esempio un valore di `reasoning_effort` fuori dalla sua lista | Correggi il valore seguendo il testo dell'errore |
| 401 `authentication_error` | Chiave non trovata, revocata o dal formato sconosciuto | Controlla la chiave nella pagina [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | Il saldo non copre la stima della richiesta; il residuo è in `balance_ngonka` | Ricarica il saldo: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Richiesta senza chiave e non dal sito (`is_demo: true`) | Passa la API key |
| 402 `child_key_limit_exceeded` | Superato il limite di spesa della chiave — giornaliero, mensile o totale; i residui sono in `daily_remaining, monthly_remaining, total_remaining` | Alza il limite della chiave nella pagina [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) oppure attendi il reset |
| 403 `forbidden` | Chiave di gestione `gm-` in una richiesta al modello; API key su un percorso riservato alla dashboard | Per le richieste usa la chiave `jg-` o `gc-`; per gestire l'account usa la dashboard |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: il modello non è nel catalogo o è temporaneamente nascosto | Prendi l'id da `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` e altri indirizzi di stato, `/v1/responses/compact` | Conserva la cronologia da te; per Codex CLI imposta il tuo id di provider |
| 404 `invalid_request_error` | Percorso sconosciuto | Controlla metodo, percorso e indirizzo di base |
| 413 `invalid_request_error` | Corpo della richiesta oltre il limite | Riduci la richiesta |
| 415 `invalid_request_error` | Il corpo non è JSON secondo l'header: serve `Content-Type: application/json` | Invia `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Superato il numero di richieste al minuto per chiave; nel corpo c'è `rate_limit` con `limit, remaining, reset` | Attendi il numero di secondi indicato in `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Modello sovraccarico nella rete Gonka | Riprova dopo `Retry-After` oppure scegli un altro modello — [Modelli](https://gate.joingonka.ai/it/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Tutti i posti verso la rete sono occupati: la coda è piena o l'attesa è scaduta | Riprova dopo `Retry-After` |
| 500 `server_error` | Errore interno del gateway | Riprova più tardi; se persiste, scrivi al supporto allegando `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: nella rete non ci sono modelli di embedding | Usa un altro servizio di embedding |
| 502 `api_error` `upstream_unauthorized` | Il provider della rete ha rifiutato le credenziali del gateway — la tua chiave è a posto | Riprova tra un minuto |
| 502 `api_error` | Errore della rete Gonka; `code` proviene dalla rete, se lo ha inviato | Riprova con una pausa oppure scegli un altro modello |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Il modello al momento non è disponibile secondo i probe della rete: guasto, avvio, instabilità o nessuno lo sta servendo; rifiuto immediato, senza attesa | Scegli un altro modello — il testo dell'errore ti dirà quale; l'elenco è in [Modelli](https://gate.joingonka.ai/it/docs/models) |
| 503 `service_unavailable` | Nessun nodo disponibile | Riprova più tardi |
| 504 `timeout` `upstream_timeout` | La rete ha accettato la richiesta ma non ha risposto in tempo; la stima dei token di input è già stata addebitata | Per le risposte lunghe usa `stream: true`; un nuovo tentativo comporta un nuovo addebito |

## Errori nello stream aperto

Finché lo stream non è aperto, il rifiuto arriva con un normale codice di risposta — come senza stream. Dopo l'apertura lo stato è già `200` e l'errore arriva così:

- Chat Completions — chunk `joingonka-error` con il campo `error`, poi interruzione senza `[DONE]`.
- Senza stream dopo una risposta anticipata — stato `200` e corpo con il campo `error`.
- Anthropic Messages — evento `event: error`, poi lo stream si chiude.
- OpenAI Responses — evento `response.failed`, causa in `response.error.code`.
- Legacy Completions — `data: {"error": …}`, poi `[DONE]`.

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

## Formato degli errori Anthropic

- `POST /v1/messages` risponde con l'envelope Anthropic: `{"type": "error", "error": {"type", "message"}}`.
- I rifiuti del gateway mantengono il `type` dalla tabella sopra (`insufficient_funds`, `model_unavailable` e altri); il campo `code` non esiste in questo envelope — la causa è nel testo.
- Errori nella forma della richiesta — `invalid_request_error`: mancano i messaggi o `max_tokens`, chiamata a uno strumento senza nome, modello sconosciuto.
- Percorso sconosciuto — `not_found_error`, corpo troppo grande — `request_too_large`.

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

## Cosa ritentare

- Dopo la pausa indicata in `Retry-After`: `429`
- Con pause crescenti — 1, 2, 4 s e oltre: `500`, `502`, `503 service_unavailable`, `504`
- Con un altro modello: `503 model_unavailable`
- Non ritentare senza modifiche — correggi la richiesta, la chiave o il saldo: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Ogni tentativo dopo `504` comporta un nuovo addebito della stima di input; per le risposte lunghe attiva `stream: true`.

Se l'errore si ripete, scrivi al supporto allegando `x-request-id` dagli header della risposta.