Source: https://ailoot.ai/docs/it/errors/ Canonical: https://ailoot.ai/docs/it/errors/ Language: it [Aiuto](https://ailoot.ai/docs/it/) # Errori e limiti [Markdown](https://ailoot.ai/docs/it/errors/index.md) Codici di risposta, significato e azioni da intraprendere. Tutti gli errori sono in JSON e contengono un Request ID. ## [](https://ailoot.ai/docs/it/errors/#format)Formato dell’errore 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. ```json { "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 \". 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. …" } ``` ```json { "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" } ``` ```json { "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" } ] } } ``` “Nothing was charged” significa che non è stato addebitato denaro. Se ricevi X-Should-Retry: false, non ripetere automaticamente: controlla prima il Request ID nella cronologia. ## [](https://ailoot.ai/docs/it/errors/#codes)Codici di errore | HTTP | Classe (reason) | Cosa è successo | Cosa fare | | --- | --- | --- | --- | | 400 | `invalid_request` | Richiesta non valida: corpo o parametro errato; il modello non supporta un campo, allegato o strumento della richiesta; chiave inviata nell’indirizzo | Correggi la richiesta in base al testo dell’errore: rimuovi il campo, allegato o strumento non supportato; trasmetti la chiave nell’header. Il rifiuto per un campo, allegato o strumento non supportato avviene prima della riserva — non è stato addebitato nulla | | 400 | `context_length_exceeded` | La richiesta supera il contesto del modello | Riduci la cronologia o scegli un modello con contesto più ampio | | 400 | `content_policy_violation` | Richiesta rifiutata dalle regole del modello | Riformula la richiesta | | 401 | `invalid_api_key` | La chiave manca o non è valida | Controlla che la chiave sia stata trasmessa per intero | | 401 | `api_key_disabled` | Chiave disattivata | Attiva la chiave o creane una nuova | | 402 | `insufficient_balance`, `insufficient_quota` | Il saldo libero non basta nemmeno per la riserva minima (`insufficient_quota` — lo stesso caso nel formato familiare a OpenAI SDK) | Ricarica il saldo o riduci max\_tokens | | 402 | `api_key_quota_exhausted` | Limite totale di spesa della chiave esaurito | Aumenta il limite della chiave nell’area personale | | 402 | `payment_disputed` | L’account ha un debito per un pagamento contestato | Le nuove richieste sono sospese fino al pagamento del debito — contatta l’assistenza | | 403 | `api_key_expired` | Chiave scaduta | Crea una nuova chiave | | 403 | `account_inactive` | Account disattivato | Contatta l’assistenza | | 403 | `permission_denied` | La richiesta non è consentita per la chiave (ad esempio per IP) | Controlla le restrizioni della chiave | | 404 | `model_not_found` | Il modello non esiste | Confronta l’ID con /v1/models | | 404 | `unsupported_endpoint` | Il modello non funziona in questo formato | Scegli un altro formato o modello | | 404 | `not_found` | Il percorso o l’oggetto (ad esempio l’attività) non esiste | Controlla indirizzo e identificatore | | 409 | `duplicate_request` | L’operazione con la stessa chiave di idempotenza è già stata accettata e potrebbe essere conclusa | Controlla il risultato della prima operazione; non inviarne una nuova | | 409 | `not_ready`, `video_not_ready` | Il video o un’altra attività non è ancora pronto | Richiedi lo stato più tardi | | 409, 503 | `result_pending_check` | Stiamo chiarendo il risultato della richiesta. Per un’attività video è il flag `result_pending_check: true` nella risposta di stato, mentre l’attività resta `in_progress` | Non ripetere la richiesta — lo stato apparirà nella cronologia (GET https://ailoot.ai/api/v1/usage). Non ricreare l’attività video: controllala più tardi tramite GET /v1/videos/{id} | | 410 | `model_retired` | Il modello è stato ritirato dal servizio | Scegli una nuova versione in GET /v1/models | | 413 | `request_too_large` | Il corpo della richiesta è troppo grande | Riduci i file o la cronologia | | 429 | `rate_limit_exceeded`, `gateway_concurrency_limit`, `gateway_queue_full` | Troppe richieste o richieste simultanee dal tuo account | Attendi (header `Retry-After`, normalmente 10 s) e riprova | | 429 | `usage_limit_reached` | Finestra di spesa della chiave esaurita (5 ore, 1 giorno o 7 giorni) | Attendi il rinnovo della finestra o aumenta il limite della chiave | | 500 | `internal_error` | Errore Ailoot | Contatta l’assistenza con il Request ID | | 502 | `invalid_model_response`, `empty_response`, `incomplete_response` | Il modello ha restituito una risposta non valida, vuota o incompleta | Trova il Request ID nella cronologia dell’area personale. Se è presente un risultato o un addebito, ripetere la richiesta ne creerà una seconda a pagamento. L’assenza di una voce non conferma che la richiesta non sia stata inviata o eseguita: non ripetere un invio non confermato; contatta l’assistenza indicando il Request ID. | | 502 | `result_not_delivered` | Risultato non consegnato per colpa di Ailoot; riserva o addebito restituiti | La richiesta può essere inviata di nuovo | | 503 | `model_overloaded` | Il modello è temporaneamente sovraccarico | Se X-Should-Retry: true — riprova dopo Retry-After secondi; se false — controlla prima il Request ID nella cronologia | | 503 | `model_unavailable` | Il modello è temporaneamente non disponibile | Scegli un altro modello. Se X-Should-Retry: true — riprova dopo Retry-After secondi; se false — controlla prima il Request ID nella cronologia | | 503 | `service_unavailable` | Errore temporaneo lato Ailoot | Se X-Should-Retry: true — riprova dopo Retry-After secondi; se false — controlla prima il Request ID nella cronologia | | 503 | `charge_not_confirmed` | Risposta non consegnata: impossibile confermare l’addebito; riserva restituita, denaro non addebitato | Se X-Should-Retry: true — riprova dopo Retry-After secondi; se false — controlla prima il Request ID nella cronologia | | 504 | `model_timeout` | Il modello non ha risposto in tempo; il risultato potrebbe ancora arrivare | Non inviare di nuovo la richiesta prima di aver controllato il Request ID nella cronologia | 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](https://ailoot.ai/docs/it/support/). ## [](https://ailoot.ai/docs/it/errors/#retry)Quando ripetere una richiesta - **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. Gli SDK OpenAI e Anthropic di solito ripetono automaticamente errori di rete e 5xx. Per le generazioni disabilita questo comportamento (`max_retries=0`) e controlla `X-Should-Retry` prima di un nuovo tentativo. Una risposta persa non significa che la richiesta non sia stata eseguita. ## [](https://ailoot.ai/docs/it/errors/#limits)Limiti 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](https://ailoot.ai/docs/it/support/). 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](https://ailoot.ai/docs/it/keys/#key). ## [](https://ailoot.ai/docs/it/errors/#nvidia)Modelli NVIDIA: coda 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](https://ailoot.ai/models/it/). ## Cronologia e spese [Cronologia e spese](https://ailoot.ai/usage) · [GET https://ailoot.ai/api/v1/usage](https://ailoot.ai/docs/it/cabinet/usage/) · JWT · `Authorization: Bearer $TOKEN` `JWT ≠ sk-…` · [Accesso e sessioni](https://ailoot.ai/docs/it/cabinet/auth/) Hai altre domande? Invia il Request ID e una descrizione — ti aiuteremo a chiarire il problema.[Contatta l’assistenza](mailto:support@ailoot.ai) ## Ailoot · L’azienda e il suo portafoglio di progetti Ailoot si basa su un’esperienza operativa consolidata, un’ampia base di clienti, un servizio stabile e un controllo costante dei KPI. L’azienda e il suo portafoglio di progetti: milioni di clienti; vendite nell’ordine dei miliardi ogni mese. Ailoot mette questa esperienza operativa al servizio dell’accesso API alle funzioni AI nei prodotti dei clienti, negli agenti, nelle applicazioni e nelle automazioni.