Errori e limiti

L’errore arriva nel formato dell’API chiamata: oggetto error per OpenAI, {"type": "error", "error": {...}} per Anthropic e error con i campi status e details per Gemini. Gli SDK quindi li riconoscono come normali errori API.

• error.code e error.reason — classe dell’errore nella tabella sotto; i valori coincidono. error.type — valore standard del formato (ad esempio invalid_request_error oppure server_error).
• error.request_id (in Anthropic — request_id al primo livello), l’header X-Request-ID e la fine del messaggio contengono l’identificatore della richiesta.
• In Gemini la classe si trova in error.details: ErrorInfo.reason — lo stesso codice in maiuscolo (ad esempio MODEL_OVERLOADED), domain — ailoot.ai; l’identificatore della richiesta è in RequestInfo.requestId.
• Nel formato Gemini un errore 5xx che non va ripetuto automaticamente e result_pending_check arrivano con stato 409 e status ABORTED: così Gemini SDK e CLI non li ripetono da soli. La classe dell’errore è in ErrorInfo.reason (ad esempio MODEL_TIMEOUT oppure RESULT_PENDING_CHECK).
• La risposta nel formato OpenAI contiene anche i campi di primo livello code e message — per i client precedenti.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

I codici per le risposte del modello e la verifica del risultato (502, 503 e 504) ora fanno riferimento al modello o alla richiesta: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed e result_pending_check. Se il tuo codice confronta error.code con i valori precedenti, sostituiscili con i codici della tabella; la corrispondenza tra codici vecchi e nuovi può essere indicata dal servizio di assistenza.

• Controlla prima X-Should-Retry: con false, result_pending_check oppure model_timeout non ripetere automaticamente. Trova il Request ID nella cronologia dell’area personale: mostra risultato e addebito.
• Ripetere è sicuro quando ricevi X-Should-Retry: true: attendi Retry-After secondi. Per 5xx il solo codice non basta: il risultato potrebbe già essere arrivato. Controlla prima la cronologia nell’area personale o contatta l’assistenza con il Request ID. È particolarmente importante per immagini, video, musica e passaggi lunghi degli agenti.
• Ripetere non aiuta: 400, 401, 402, 403, 404 — correggi prima richiesta, chiave o saldo.

La frequenza e il numero di richieste simultanee sono limitati per l’intero account, non per la singola chiave. Superando il limite ricevi 429 rate_limit_exceeded con l’header Retry-After: 10. Se è il modello stesso a essere sovraccarico — 503 model_overloaded con Retry-After: 30. Se ti serve un carico maggiore, scrivi al servizio di assistenza.

I limiti di spesa si impostano sulla chiave: limite totale — 402 api_key_quota_exhausted, finestre di 5 ore, 1 giorno e 7 giorni — 429 usage_limit_reached. Per approfondire — Chiavi e indirizzo API.

Puoi richiedere l’elenco dei modelli anche con saldo zero; la generazione richiede saldo per la riserva. I modelli NVIDIA (Nemotron e altri) usano una coda condivisa: con carico elevato la risposta può arrivare più tardi oppure viene restituito l’errore «modello temporaneamente sovraccarico» con l’header Retry-After — riprova dopo il tempo indicato. I prezzi sono nel catalogo e gli addebiti funzionano come per gli altri modelli.

I limiti di dimensione sono stabiliti dal modello: contesto (quanti token puoi inviare) e lunghezza massima della risposta. Sono indicati nel catalogo.