Per gli agenti AI: guida passo passo alla configurazione — /docs/agents.md, indice della documentazione — /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.

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

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.

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.

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

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].

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

• 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.

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

• 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.