> ## 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 progetto non è in uno stato che consente la richiesta |
| 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** - La trascrizione non è stata completata |

## 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` | La trascrizione non è stata completata |
| 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 | `INVALID_TRANSLATED_SRT` | translatedSrt non contiene cue SRT validi |
| 400 | `TRANSLATED_SRT_CUE_COUNT_MISMATCH` | Il numero di cue di translatedSrt e sourceSrt è diverso |
| 409 | `DUB_ONLY_REQUIRES_TRANSCRIPTION` | Il progetto non ha una trascrizione completata da doppiare |
| 409 | `TRANSLATION_ALREADY_IN_PROGRESS` | Un doppiaggio è già in corso per la lingua |
| 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 selezionata non è una voce del catalogo né una voce personalizzata salvata dall’account autenticato. |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | La modalità di sincronizzazione labiale premium non è disponibile nel piano |

## Errori asincroni di allineamento SRT

Questi errori si verificano dopo l’accettazione di una richiesta di traduzione o doppiaggio. L’endpoint di stato risponde con HTTP 200 e `status: "failed"`; il suo `error` e il webhook `project.translation.failed` contengono solo `code` e `message`. Gli errori salvati usano messaggi fissi di VoiceCheap; non includono numeri dei cue né indici dei segmenti. Gli errori sincroni della richiesta, tra cui `TRANSLATED_SRT_CUE_COUNT_MISMATCH`, restano HTTP 400 nella tabella precedente.

| Risultato | Code | Significato |
| - | - | - |
| `GET` 200 / webhook | `TRANSLATED_SRT_UNMATCHED_CUES` | Un cue tradotto non corrisponde ad alcun segmento della trascrizione (segnalato da stato e webhook) |
| `GET` 200 / webhook | `TRANSLATED_SRT_MISSING_SEGMENTS` | Un segmento della trascrizione non ha un cue tradotto (segnalato da stato e webhook) |

## Errori di autenticazione

> [accordion] MISSING\_API\_KEY
>
> **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."
> }
> ```

> [accordion] INVALID\_API\_KEY\_FORMAT
>
> **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_\"."
> }
> ```

> [accordion] INVALID\_API\_KEY
>
> **Stato HTTP:** 401
>
> La chiave API fornita non è valida.
>
> **Soluzione:** Verifica che la tua chiave API sia corretta e inclusa nell'intestazione `x-api-key`.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY",
>   "message": "Invalid API key. Please check your API key and try again."
> }
> ```

> [accordion] SUBSCRIPTION\_REQUIRED
>
> **Stato HTTP:** 403
>
> L'accesso all'API e a MCP richiede un piano Starter o superiore.
>
> **Soluzione:** Passa a un piano Starter o superiore su [voicecheap.ai](https://voicecheap.ai/pricing).
>
> ```json theme={null}
> {
>   "code": "SUBSCRIPTION_REQUIRED",
>   "message": "A Starter plan or higher is required to use the API and MCP. Please upgrade your account at voicecheap.ai/pricing."
> }
> ```

> [accordion] INSUFFICIENT\_CREDITS
>
> **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."
> }
> ```

## Altri errori di autenticazione e team

| HTTP | Codice | Descrizione |
| - | - | - |
| 401 | `USER_NOT_FOUND` | L’account associato a questa chiave non è stato trovato |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | Il titolare della chiave appartiene a più team; contatta l’assistenza |
| 403 | `TEAM_OWNER_NOT_FOUND` | L’account del proprietario del team collegato non è stato trovato |

## Errori di convalida del file

> [accordion] FILE\_REQUIRED
>
> **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."
> }
> ```

> [accordion] INVALID\_FILE\_TYPE
>
> **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, ..."
> }
> ```

> [accordion] FILE\_TOO\_LARGE
>
> **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
> }
> ```

> [accordion] DURATION\_DETECTION\_FAILED
>
> **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

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **Stato HTTP:** 400
>
> La lingua di destinazione specificata non è supportata.
>
> **Soluzione:** Utilizza una delle [lingue supportate](https://api-docs.voicecheap.ai/docs/it/introduction.md#supported-languages).
>
> ```json theme={null}
> {
>   "code": "VALIDATION_ERROR",
>   "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
> }
> ```

> [accordion] INVALID\_BOOLEAN\_VALUE
>
> **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\"."
> }
> ```

> [accordion] INVALID\_JSON\_FORMAT
>
> **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."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **Stato HTTP:** 400
>
> Un campo form-data numerico opzionale non era un numero valido. Inviare un valore numerico entro l'intervallo documentato.

> [accordion] LIPSYNC\_VIDEO\_TOO\_LONG
>
> **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 180 minutes. Your video is 181 minutes long."
> }
> ```

## Errori delle risorse

> [accordion] PROJECT\_NOT\_FOUND
>
> **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."
> }
> ```

> [accordion] FORBIDDEN
>
> **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."
> }
> ```

## Errori di autorizzazione e utilizzo

| Stato | Codice | Azione |
| - | - | - |
| 401 | `API_KEY_EXPIRED`, `INVALID_MCP_TOKEN` | Usa una chiave valida e non scaduta oppure ricollega l'assistente. |
| 403 | `INSUFFICIENT_SCOPE` | Concedi l'autorizzazione richiesta oppure scegli un'altra credenziale. |
| 403 | `SUBSCRIPTION_REQUIRED` | Usa un piano Starter o superiore. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Attendi l'azzeramento mensile oppure cambia piano. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED` | Attendi prima di riprovare e aumenta progressivamente l'intervallo tra i tentativi. |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Attendi il completamento di una generazione in corso. |
| 400 | `VALIDATION_ERROR` | Correggi gli argomenti usando lo schema di input del catalogo. |
| 404 | `UNKNOWN_ACTION` | Usa un nome di azione supportato restituito dalla discovery. |

Consulta [utilizzo e limiti](https://api-docs.voicecheap.ai/docs/it/api-reference/limits.md) per la quota condivisa dell'account. Gli errori non consumano chiamate mensili. `action_request_get`, `usage_get`, `projects_status` e `GET /v1/translate/{projectId}/status` sono esenti dalla quota mensile.

## Errori di elaborazione

Questi errori possono essere restituiti nel campo `error` durante il controllo dello stato della traduzione:

> [accordion] TRANSCRIPTION\_FAILED
>
> 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": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] TRANSLATION\_FAILED
>
> Non è stato possibile tradurre la trascrizione.
>
> **Possibili cause:**
>
> * Coppia linguistica non supportata
> * Impossibile elaborare il contenuto
>
> ```json theme={null}
> {
>   "code": "TRANSLATION_FAILED",
>   "message": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] LIPSYNC\_FAILED
>
> L'elaborazione della sincronizzazione labiale non è riuscita.
>
> **Possibili cause:**
>
> * Un problema temporaneo durante la sincronizzazione labiale
> * Media non valido o non supportato
> * La richiesta è stata rifiutata o annullata
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## Errori del server

> [accordion] INTERNAL\_ERROR
>
> **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}")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.