> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Errori ## Errori API ElevenLabs utilizza codici di stato HTTP standard per indicare l'esito positivo o negativo di una richiesta. Inoltre, tutte le richieste API restituiscono un oggetto JSON con una proprietà `detail` contenente informazioni sull'errore. In generale, un codice di stato HTTP `200` indica che la richiesta è stata completata correttamente. Un codice `4xx` indica un problema con la richiesta, ad esempio un parametro non valido o un campo obbligatorio mancante. Un codice di stato HTTP `500` indica un problema con i server di ElevenLabs, che dovrebbe verificarsi raramente. ### Proprietà dell'errore | Proprietà | Descrizione | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `type` | Il tipo di errore che si è verificato. Consulta la tabella seguente per i valori possibili. | | `code` | Il codice dell'errore. È più specifico del tipo e può essere usato per determinare la causa dell'errore. | | `message` | Il messaggio dell'errore. Fornisce maggiori dettagli sull'errore. | | `status` | Lo stato dell'errore. È un campo legacy che non viene più utilizzato; usa invece la proprietà `code`. | | `request_id` | L'ID della richiesta relativa all'errore. È un identificatore univoco della richiesta che può essere usato per risolvere il problema. | | `param` | Il parametro che ha causato l'errore. In caso di errore di convalida, indica il parametro non valido. | ### Esempio di risposta di errore Ecco la risposta a una richiesta API che ha utilizzato un ID modello errato: ```json { "detail": { "type": "validation_error", "code": "invalid_parameters", "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.", "status": "invalid_parameters", "request_id": "3c807fc4c3a1705f9638ecc764a91c01", "param": "keyterms" } } ``` Dalle proprietà dell'errore, possiamo vedere che si tratta di un errore di convalida e che il codice è `invalid_parameters`. Il messaggio fornisce maggiori dettagli sull'errore e `request_id` è un identificatore univoco della richiesta che può essere usato per risolvere il problema. La proprietà `param` indica il parametro che ha causato l'errore. ### Gestione degli errori negli SDK Gli SDK di ElevenLabs forniscono classi di errore tipizzate che ti consentono di accedere ai dettagli dell'errore. ```python from elevenlabs import ElevenLabs from elevenlabs.core import ApiError elevenlabs = ElevenLabs() try: audio = elevenlabs.text_to_speech.convert( voice_id="invalid-voice-id", model_id="eleven_v4", text="Hello, world!", ) except ApiError as e: print(f"Status code: {e.status_code}") # Access the error body if e.body and "detail" in e.body: detail = e.body["detail"] print(f"Error type: {detail.get('type')}") print(f"Error code: {detail.get('code')}") print(f"Message: {detail.get('message')}") print(f"Request ID: {detail.get('request_id')}") # Handle specific error types if detail.get("type") == "rate_limit_error": print("Rate limited - implement exponential backoff") elif detail.get("type") == "authentication_error": print("Check your API key") ``` ```typescript import { ElevenLabsClient, ElevenLabsError } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); try { const audio = await elevenlabs.textToSpeech.convert("invalid-voice-id", { text: "Hello, world!", modelId: "eleven_v4", }); } catch (error) { if (error instanceof ElevenLabsError) { console.log(`Status code: ${error.statusCode}`); // Access the error body const detail = (error.body as any)?.detail; if (detail) { console.log(`Error type: ${detail.type}`); console.log(`Error code: ${detail.code}`); console.log(`Message: ${detail.message}`); console.log(`Request ID: ${detail.request_id}`); // Handle specific error types if (detail.type === "rate_limit_error") { console.log("Rate limited - implement exponential backoff"); } else if (detail.type === "authentication_error") { console.log("Check your API key"); } } } } ``` Se non riesci a risolvere l'errore, invia un'email al Supporto all'indirizzo [support@elevenlabs.io](mailto:support@elevenlabs.io) includendo il `request_id` della risposta di errore, il messaggio di errore completo e i passaggi per riprodurre il problema. #### Limitazione della frequenza e concorrenza Se ricevi un codice di stato HTTP 429, significa che hai effettuato troppe richieste in un breve periodo e hai superato il limite di frequenza per l'endpoint API, oppure hai superato il limite di concorrenza per l'endpoint API. Il `code` dell'errore sarà rispettivamente `rate_limit_exceeded` o `concurrent_limit_exceeded`. In caso di limitazione della frequenza, dovresti implementare un backoff esponenziale nel codice quando ricevi un errore 429. Ciò significa aggiungere un ritardo prima di riprovare la richiesta. In caso di concorrenza, dovresti attendere il completamento delle richieste correnti prima di effettuarne di nuove. Per maggiori informazioni, consulta la sezione [Concorrenza e priorità](/docs/it/overview/models#concurrency-and-priority). ### Tipi di errore Un errore include una proprietà `type` che indica il tipo di errore verificatosi. Consulta la tabella seguente per i valori possibili. | Tipo | Descrizione | Codice di stato HTTP | | ---------------------- | ----------------------------------------------------------------------------------- | -------------------- | | `validation_error` | La richiesta contiene valori di parametro non validi. | 400 | | `invalid_request` | La struttura della richiesta non è valida o mancano campi obbligatori. | 400 | | `authentication_error` | Autenticazione non riuscita: chiave API/token non valido o mancante. | 401 | | `payment_required` | L'utente non dispone di crediti sufficienti oppure è richiesto un pagamento. | 402 | | `authorization_error` | L'utente autenticato non dispone delle autorizzazioni necessarie per questa azione. | 403 | | `not_found` | La risorsa richiesta non è stata trovata. | 404 | | `conflict` | La richiesta è in conflitto con lo stato corrente della risorsa. | 409 | | `rate_limit_error` | Troppe richieste: riprova più tardi. | 429 | | `internal_error` | Si è verificato un errore del server imprevisto. | 500 | | `service_unavailable` | Il servizio è temporaneamente non disponibile; dovrebbe verificarsi raramente. | 503 | ### Codici di errore
Codice Tipo Descrizione
`voice_not_found` `not_found` L'ID della voce specificato non esiste. Verifica l'ID della voce e riprova.
`sample_not_found` `not_found` Il campione vocale specificato non è stato trovato.
`voice_collection_not_found` `not_found` La raccolta di voci specificata non esiste.
`user_not_found` `not_found` L'utente specificato non è stato trovato.
`auth_account_not_found` `not_found` L'account di autenticazione non è stato trovato.
`workspace_not_found` `not_found` Il workspace specificato non esiste.
`project_not_found` `not_found` Il progetto specificato non è stato trovato.
`history_item_not_found` `not_found` L'elemento della cronologia specificato non esiste.
`collection_not_found` `not_found` La raccolta specificata non è stata trovata.
`document_not_found` `not_found` Il documento specificato non esiste.
`file_not_found` `not_found` Il file specificato non è stato trovato.
`conversation_not_found` `not_found` La conversazione specificata non esiste.
`agent_not_found` `not_found` L'agente specificato non è stato trovato.
`dubbing_not_found` `not_found` Il progetto di doppiaggio specificato non esiste.
`song_not_found` `not_found` Il brano specificato non è stato trovato.
`read_not_found` `not_found` La lettura specificata non è stata trovata.
`pronunciation_dictionary_not_found` `not_found` Il dizionario di pronuncia specificato non esiste.
`knowledge_base_not_found` `not_found` La knowledge base specificata non è stata trovata.
`phone_number_not_found` `not_found` Il numero di telefono specificato non esiste.
`tool_not_found` `not_found` Lo strumento specificato non è stato trovato.
`snapshot_not_found` `not_found` Lo snapshot specificato non esiste.
`task_not_found` `not_found` L'attività specificata non è stata trovata.
`model_not_found` `not_found` Il modello specificato non esiste.
`transcript_not_found` `not_found` La trascrizione specificata non è stata trovata.
`keywords_list_not_found` `not_found` L'elenco di parole chiave specificato non è stato trovato.
`category_not_found` `not_found` La categoria specificata non è stata trovata.
`text_too_long` `validation_error` Il testo fornito supera la lunghezza massima consentita.
`text_too_short` `validation_error` Il testo fornito è più breve della lunghezza minima richiesta.
`invalid_text` `validation_error` Il testo fornito contiene caratteri o formattazione non validi.
`empty_text` `validation_error` Il campo di testo non può essere vuoto.
`invalid_parameters` `validation_error` Uno o più parametri della richiesta non sono validi. Controlla la proprietà `param` per il parametro non valido.
`missing_required_field` `validation_error` Manca un campo obbligatorio nella richiesta. Controlla la proprietà `param` per il campo mancante.
`invalid_voice_settings` `validation_error` Le impostazioni della voce contengono valori non validi. Controlla la proprietà `param` per le impostazioni della voce non valide.
`invalid_voice_id` `validation_error` Il formato dell'ID della voce non è valido.
`unsupported_model` `validation_error` Il modello specificato non è supportato per questa operazione.
`invalid_audio` `validation_error` L'audio fornito non è valido o è danneggiato.
`invalid_audio_format` `validation_error` Il formato audio specificato non è supportato.
`invalid_output_format` `validation_error` Il formato di output richiesto non è supportato.
`audio_too_long` `validation_error` L'audio supera la durata massima consentita.
`audio_too_short` `validation_error` L'audio è più breve della durata minima richiesta.
`invalid_file_type` `validation_error` Il tipo di file non è supportato.
`invalid_page_size` `validation_error` Il parametro relativo alla dimensione della pagina è al di fuori dell'intervallo consentito.
`invalid_cursor` `validation_error` Il cursore di paginazione non è valido o è scaduto.
`bad_request` `invalid_request` Il server non ha potuto comprendere la richiesta.
`malformed_json` `invalid_request` Il body della richiesta contiene JSON non valido.
`invalid_content_type` `invalid_request` L'header Content-Type è mancante o non valido.
`request_too_large` `invalid_request` Il body della richiesta supera la dimensione massima consentita.
`invalid_api_key` `authentication_error` La chiave API fornita non è valida.
`missing_api_key` `authentication_error` Nella richiesta non è stata fornita alcuna chiave API.
`invalid_authorization_header` `authentication_error` Il formato dell'header Authorization non è valido.
`unauthorized` `authentication_error` Per accedere a questa risorsa è necessaria l'autenticazione.
`sign_in_required` `authentication_error` Devi aver effettuato l'accesso per eseguire questa azione.
`forbidden` `authorization_error` L'accesso a questa risorsa è vietato.
`insufficient_permissions` `authorization_error` Non disponi delle autorizzazioni necessarie per questa azione.
`workspace_access_denied` `authorization_error` Non hai accesso a questo workspace.
`feature_not_available` `authorization_error` Questa funzionalità non è disponibile nel tuo piano attuale.
`subscription_required` `authorization_error` Per accedere a questa funzionalità è richiesto un abbonamento a pagamento.
`voice_access_denied` `authorization_error` Non hai accesso a questa voce.
`model_access_denied` `authorization_error` Non hai accesso a questo modello.
`conflict` `conflict` Si è verificato un conflitto.
`resource_already_exists` `conflict` Esiste già una risorsa con lo stesso identificatore.
`voice_already_exists` `conflict` Esiste già una voce con questo nome.
`already_running` `conflict` L'operazione è già in esecuzione.
`already_processing` `conflict` La risorsa è già in fase di elaborazione.
`concurrent_modification` `conflict` La risorsa è stata modificata da un'altra richiesta. Riprova con la versione più recente.
`slug_already_exists` `conflict` Esiste già una risorsa con questo slug.
`rate_limit_exceeded` `rate_limit_error` Troppe richieste. Attendi prima di riprovare.
`concurrent_limit_exceeded` `rate_limit_error` È stato superato il numero massimo di richieste simultanee. I piani di abbonamento superiori hanno un limite di concorrenza più elevato.
`system_busy` `rate_limit_error` Il sistema è attualmente occupato. Riprova più tardi.
`insufficient_credits` `payment_required` Il tuo account non dispone di crediti sufficienti per questa operazione.
`internal_error` `internal_error` Si è verificato un errore imprevisto. Contatta il supporto se il problema persiste.
`service_unavailable` `service_unavailable` Il servizio è temporaneamente non disponibile. Riprova più tardi.
`maintenance` `service_unavailable` Il servizio è sottoposto a manutenzione programmata.