> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Codici di errore
> Riferimento completo dei codici di errore restituiti dall'API VoiceCheap
# Codici di errore
L'API VoiceCheap utilizza codici di stato HTTP standard e restituisce risposte di errore strutturate per aiutarti a gestire gli errori in modo appropriato.
## Formato della risposta di errore
Tutte le risposte di errore seguono questa struttura:
```json theme={null}
{
"code": "ERROR_CODE",
"message": "Human-readable description of the error"
}
```
Alcuni errori possono includere campi aggiuntivi. Gli errori di convalida del payload della richiesta restituiscono una voce per
campo non valido in `details`, e `field` viene omesso quando il messaggio di vincolo non specifica una
proprietà specifica:
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Request validation failed.",
"details": [
{
"field": "outputFormat",
"messages": ["outputFormat must be one of the following values: json, srt, vtt"]
}
]
}
```
## Codici di stato HTTP
| Codice di stato | Significato |
| --------------- | -------------------------------------------------------------------- |
| 200 | **OK** - Richiesta riuscita |
| 400 | **Bad Request** - Parametri non validi o errore di convalida |
| 401 | **Unauthorized** - Chiave API non valida o mancante |
| 403 | **Forbidden** - Chiave API valida ma autorizzazioni insufficienti |
| 404 | **Not Found** - La risorsa non esiste |
| 409 | **Conflict** - Il risultato richiesto non è pronto |
| 413 | **Payload Too Large** - Il file caricato supera il limite consentito |
| 429 | **Too Many Requests** - Limite di frequenza superato |
| 500 | **Internal Server Error** - Qualcosa è andato storto da parte nostra |
| 502 | **Bad Gateway** - Un motore di elaborazione ha fallito |
## Errori di trascrizione ed esportazione della trascrizione
| Stato | Codice | Significato |
| ----- | --------------------------- | ------------------------------------------------------------------------ |
| 400 | `INVALID_MEDIA_STREAM` | Il file multimediale caricato non contiene un flusso audio |
| 400 | `DURATION_TOO_LONG` | Il file multimediale per la trascrizione autonoma è più lungo di due ore |
| 400 | `INVALID_BRAND_VOCABULARY` | Una voce del glossario specifica per la richiesta viola i limiti |
| 400 | `TARGET_LANGUAGE_REQUIRED` | Una richiesta di trascrizione tradotta ha omesso la lingua |
| 404 | `TRANSCRIPT_NOT_FOUND` | La trascrizione originale o tradotta richiesta è assente |
| 409 | `TRANSCRIPT_NOT_READY` | La trascrizione richiesta è ancora in fase di elaborazione |
| 502 | `TRANSCRIPTION_EMPTY` | La trascrizione non conteneva parlato utilizzabile |
| 502 | `TRANSCRIPTION_FAILED` | Il motore di trascrizione non è riuscito a completare la richiesta |
| 400 | `INVALID_MULTIPART_REQUEST` | La richiesta di caricamento multipart è malformata o supera i limiti |
## Errori nelle opzioni di doppiaggio
| Stato | Codice | Significato |
| ----- | ----------------------------------------------- | -------------------------------------------------------------------------------------- |
| 400 | `INVALID_SOURCE_SRT` | sourceSrt non contiene cue SRT validi |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt richiede un originalLanguage esplicito |
| 400 | `VOICE_ID_REQUIRED` | La modalità voci personalizzate richiede un ID voce |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | voiceId è stato combinato con la clonazione vocale |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Le impostazioni di clonazione sono state combinate con la modalità voci personalizzate |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | I campi di sincronizzazione labiale moderni e legacy sono in conflitto |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | I salti temporali richiedono audio di sottofondo |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | I salti temporali sono in conflitto con la conservazione della voce originale |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Un salto temporale si estende oltre la durata del file multimediale |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Un salto temporale si sovrappone a un segmento di trascrizione |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | I sottotitoli impressi richiedono un input video |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | La sincronizzazione labiale richiede un input video |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | I salti temporali di traduzione richiedono un input video |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | La voce personalizzata non è di proprietà del proprietario effettivo |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | La modalità di sincronizzazione labiale premium non è disponibile nel piano |
## Errori di autenticazione
**Stato HTTP:** 401
L'intestazione `x-api-key` non è stata fornita.
**Soluzione:** Includi la tua chiave API nell'intestazione `x-api-key`.
```json theme={null}
{
"code": "MISSING_API_KEY",
"message": "API key is required. Please provide your API key in the x-api-key header."
}
```
**Stato HTTP:** 401
La chiave API non utilizza il prefisso `vc_` previsto.
**Soluzione:** Verifica di aver copiato la chiave completa dall'app VoiceCheap.
```json theme={null}
{
"code": "INVALID_API_KEY_FORMAT",
"message": "Invalid API key format. API keys must start with \"vc_\"."
}
```
**Stato HTTP:** 401
La chiave API fornita non è valida o è scaduta.
**Soluzione:** Verifica che la tua chiave API sia corretta e inclusa nell'intestazione `x-api-key`.
```json theme={null}
{
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid. Please check your API key and try again."
}
```
**Stato HTTP:** 403
L'account dispone di una chiave valida, ma l'accesso all'API non è abilitato per tale account.
**Soluzione:** Richiedi l'accesso all'API o utilizza un account che abbia già l'accesso all'API abilitato.
```json theme={null}
{
"code": "API_ACCESS_REQUIRED",
"message": "API access is required. Please request access to the API beta program."
}
```
**Stato HTTP:** 403
L'accesso all'API richiede un abbonamento a pagamento attivo.
**Soluzione:** Passa a un piano a pagamento su [voicecheap.ai](https://voicecheap.ai/pricing).
```json theme={null}
{
"code": "SUBSCRIPTION_REQUIRED",
"message": "API access requires an active paid subscription. Please upgrade your plan."
}
```
**Stato HTTP:** 403
Il tuo account non dispone di crediti sufficienti per elaborare questa richiesta.
**Soluzione:** Acquista altri crediti o aggiorna il tuo piano di abbonamento.
```json theme={null}
{
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient credits to process this file. Please add more credits to your account."
}
```
## Errori di convalida del file
**Stato HTTP:** 400
Nessun file è stato caricato con la richiesta.
**Soluzione:** Includi un file nel campo `file` dei tuoi dati del modulo multipart.
```json theme={null}
{
"code": "FILE_REQUIRED",
"message": "A video or audio file is required. Please upload a file with your request."
}
```
**Stato HTTP:** 400
Il tipo di file caricato non è supportato.
**Soluzione:** Carica un file in uno dei formati supportati (MP4, MOV, MKV, WebM, MPEG, MP3, WAV, M4A, FLAC, OGG, AAC).
```json theme={null}
{
"code": "INVALID_FILE_TYPE",
"message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
}
```
**Stato HTTP:** 413
Il file caricato supera il limite consentito per l'abbonamento autenticato: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB o Enterprise 60 GB.
**Soluzione:** Verifica il limite del tuo piano, quindi comprimi il file, dividilo in segmenti più piccoli o aggiorna il tuo piano.
```json theme={null}
{
"code": "FILE_TOO_LARGE",
"message": "File size exceeds the 5GB limit for the beginner plan.",
"maximumFileSizeBytes": 5368709120
}
```
**Stato HTTP:** 400
Impossibile rilevare la durata del file caricato.
**Soluzione:** Assicurati che il file sia un file video o audio valido e non danneggiato.
```json theme={null}
{
"code": "DURATION_DETECTION_FAILED",
"message": "Could not detect the duration of the uploaded file. Please ensure the file is a valid video or audio file."
}
```
## Errori di convalida
**Stato HTTP:** 400
La lingua di destinazione specificata non è supportata.
**Soluzione:** Utilizza una delle [lingue supportate](/docs/it/introduction#supported-languages).
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}
```
**Stato HTTP:** 400
Un parametro booleano ha ricevuto un valore non valido.
**Soluzione:** Utilizzare `true` o `false` (come stringhe in form-data).
```json theme={null}
{
"code": "INVALID_BOOLEAN_VALUE",
"message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
}
```
**Stato HTTP:** 400
Un parametro JSON non è stato possibile analizzarlo.
**Soluzione:** Assicurarsi che la stringa JSON sia formattata correttamente.
```json theme={null}
{
"code": "INVALID_JSON_FORMAT",
"message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
}
```
**Stato HTTP:** 400
Un campo form-data numerico opzionale non era un numero valido. Inviare un valore numerico entro l'intervallo documentato.
**Stato HTTP:** 400
La sincronizzazione labiale è stata richiesta per file multimediali più lunghi della durata supportata per la sincronizzazione labiale.
**Soluzione:** Omettere `lipsyncPro` per questa richiesta o inviare un file multimediale entro il limite di sincronizzazione labiale.
```json theme={null}
{
"code": "LIPSYNC_VIDEO_TOO_LONG",
"message": "LipSync supports up to 30 minutes. Your video is 45 minutes long."
}
```
## Errori delle risorse
**Stato HTTP:** 404
Il progetto specificato non esiste.
**Soluzione:** Verificare che l'ID del progetto sia corretto.
```json theme={null}
{
"code": "PROJECT_NOT_FOUND",
"message": "Project with ID 'abc123' not found."
}
```
**Stato HTTP:** 403
Non si dispone dell'autorizzazione per accedere a questa risorsa.
**Soluzione:** Assicurarsi di utilizzare la chiave API corretta per questo progetto.
```json theme={null}
{
"code": "FORBIDDEN",
"message": "You do not have permission to access this project."
}
```
## Limitazione della frequenza
**Stato HTTP:** 429
È stato superato il limite di frequenza per questo endpoint.
**Soluzione:** Attendere prima di effettuare ulteriori richieste. Utilizzare il backoff esponenziale.
| Endpoint | Limite di frequenza |
| ------------------------------- | ---------------------- |
| `POST /v1/translate` | 10 richieste al minuto |
| `POST /v1/projects` | 10 richieste al minuto |
| `GET /v1/translate/{id}/status` | 30 richieste al minuto |
| `GET /v1/projects/{id}` | 20 richieste al minuto |
| `DELETE /v1/translate/{id}` | 10 richieste al minuto |
```json theme={null}
{
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please wait before trying again."
}
```
**Stato HTTP:** 429
Si dispone già del numero massimo di traduzioni in esecuzione in parallelo.
**Soluzione:** Attendere il completamento di una delle traduzioni in corso, quindi riprovare la richiesta.
```json theme={null}
{
"code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
"message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
}
```
## Errori di elaborazione
Questi errori possono essere restituiti nel campo `error` durante il controllo dello stato della traduzione:
Non è stato possibile trascrivere l'audio.
**Possibili cause:**
* Qualità audio troppo bassa
* Nessun parlato rilevato nell'audio
* Codifica audio non supportata
```json theme={null}
{
"code": "TRANSCRIPTION_FAILED",
"message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}
```
Non è stato possibile tradurre la trascrizione.
**Possibili cause:**
* Coppia linguistica non supportata
* Impossibile elaborare il contenuto
```json theme={null}
{
"code": "TRANSLATION_FAILED",
"message": "Failed to translate the content. Please try again."
}
```
La sintesi vocale non è riuscita durante il doppiaggio.
**Possibili cause:**
* La clonazione vocale non è riuscita
* Errore di generazione audio
```json theme={null}
{
"code": "VOICE_SYNTHESIS_FAILED",
"message": "Failed to generate the dubbed audio. Please try again."
}
```
L'elaborazione della sincronizzazione labiale non è riuscita.
**Possibili cause:**
* Errore del provider di sincronizzazione labiale
* Media non valido o non supportato
* La richiesta è stata rifiutata o annullata
```json theme={null}
{
"code": "LIPSYNC_FAILED",
"message": "Lip sync failed."
}
```
## Errori del server
**Stato HTTP:** 500
Si è verificato un errore imprevisto sui nostri server.
**Soluzione:** Riprova la richiesta. Se il problema persiste, contatta l'assistenza.
```json theme={null}
{
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred. Please try again later."
}
```
## Gestione degli errori
```javascript JavaScript theme={null}
try {
const response = await fetch('https://api.voicecheap.ai/v1/translate', {
method: 'POST',
headers: { 'x-api-key': apiKey },
body: formData,
});
if (!response.ok) {
const error = await response.json();
switch (error.code) {
case 'MISSING_API_KEY':
case 'INVALID_API_KEY':
case 'INVALID_API_KEY_FORMAT':
// Check API key configuration
break;
case 'INSUFFICIENT_CREDITS':
// Prompt user to add credits
break;
case 'RATE_LIMIT_EXCEEDED':
// Implement backoff and retry
break;
case 'CONCURRENT_TRANSLATION_LIMIT_REACHED':
// Wait for an in-progress translation to finish
break;
default:
// Handle other errors
console.error(`Error: ${error.message}`);
}
}
} catch (err) {
// Handle network errors
console.error(err);
}
```
```python Python theme={null}
import requests
from requests.exceptions import RequestException
try:
response = requests.post(
'https://api.voicecheap.ai/v1/translate',
headers={'x-api-key': api_key},
files=files,
data=data
)
if response.status_code != 200:
error = response.json()
if error['code'] in ['MISSING_API_KEY', 'INVALID_API_KEY', 'INVALID_API_KEY_FORMAT']:
# Check API key configuration
pass
elif error['code'] == 'INSUFFICIENT_CREDITS':
# Prompt user to add credits
pass
elif error['code'] == 'RATE_LIMIT_EXCEEDED':
# Implement backoff and retry
pass
elif error['code'] == 'CONCURRENT_TRANSLATION_LIMIT_REACHED':
# Wait for an in-progress translation to finish
pass
else:
print(f"Error: {error['message']}")
except RequestException as e:
# Handle network errors
print(f"Network error: {e}")
```