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:

{
  "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:

{
  "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

MISSING_API_KEY

Stato HTTP: 401L’intestazione x-api-key non è stata fornita.Soluzione: Includi la tua chiave API nell’intestazione x-api-key.

{
  "code": "MISSING_API_KEY",
  "message": "API key is required. Please provide your API key in the x-api-key header."
}

INVALID_API_KEY_FORMAT

Stato HTTP: 401La chiave API non utilizza il prefisso vc_ previsto.Soluzione: Verifica di aver copiato la chiave completa dall’app VoiceCheap.

{
  "code": "INVALID_API_KEY_FORMAT",
  "message": "Invalid API key format. API keys must start with \"vc_\"."
}

INVALID_API_KEY

Stato HTTP: 401La chiave API fornita non è valida.Soluzione: Verifica che la tua chiave API sia corretta e inclusa nell’intestazione x-api-key.

{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key. Please check your API key and try again."
}

SUBSCRIPTION_REQUIRED

Stato HTTP: 403L’accesso all’API e a MCP richiede un piano Starter o superiore.Soluzione: Passa a un piano Starter o superiore su voicecheap.ai.

{
  "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."
}

INSUFFICIENT_CREDITS

Stato HTTP: 403Il tuo account non dispone di crediti sufficienti per elaborare questa richiesta.Soluzione: Acquista altri crediti o aggiorna il tuo piano di abbonamento.

{
  "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

FILE_REQUIRED

Stato HTTP: 400Nessun file è stato caricato con la richiesta.Soluzione: Includi un file nel campo file dei tuoi dati del modulo multipart.

{
  "code": "FILE_REQUIRED",
  "message": "A video or audio file is required. Please upload a file with your request."
}

INVALID_FILE_TYPE

Stato HTTP: 400Il 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).

{
  "code": "INVALID_FILE_TYPE",
  "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
}

FILE_TOO_LARGE

Stato HTTP: 413Il 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.

{
  "code": "FILE_TOO_LARGE",
  "message": "File size exceeds the 5GB limit for the beginner plan.",
  "maximumFileSizeBytes": 5368709120
}

DURATION_DETECTION_FAILED

Stato HTTP: 400Impossibile rilevare la durata del file caricato.Soluzione: Assicurati che il file sia un file video o audio valido e non danneggiato.

{
  "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

INVALID_TARGET_LANGUAGE

Stato HTTP: 400La lingua di destinazione specificata non è supportata.Soluzione: Utilizza una delle lingue supportate.

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}

INVALID_BOOLEAN_VALUE

Stato HTTP: 400Un parametro booleano ha ricevuto un valore non valido.Soluzione: Utilizzare true o false (come stringhe in form-data).

{
  "code": "INVALID_BOOLEAN_VALUE",
  "message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
}

INVALID_JSON_FORMAT

Stato HTTP: 400Un parametro JSON non è stato possibile analizzarlo.Soluzione: Assicurarsi che la stringa JSON sia formattata correttamente.

{
  "code": "INVALID_JSON_FORMAT",
  "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
}

INVALID_NUMBER_VALUE

Stato HTTP: 400Un campo form-data numerico opzionale non era un numero valido. Inviare un valore numerico entro l’intervallo documentato.

LIPSYNC_VIDEO_TOO_LONG

Stato HTTP: 400La 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.

{
  "code": "LIPSYNC_VIDEO_TOO_LONG",
  "message": "LipSync supports up to 180 minutes. Your video is 181 minutes long."
}

Errori delle risorse

PROJECT_NOT_FOUND

Stato HTTP: 404Il progetto specificato non esiste.Soluzione: Verificare che l’ID del progetto sia corretto.

{
  "code": "PROJECT_NOT_FOUND",
  "message": "Project with ID 'abc123' not found."
}

FORBIDDEN

Stato HTTP: 403Non si dispone dell’autorizzazione per accedere a questa risorsa.Soluzione: Assicurarsi di utilizzare la chiave API corretta per questo progetto.

{
  "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 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:

TRANSCRIPTION_FAILED

Non è stato possibile trascrivere l’audio.Possibili cause:

Qualità audio troppo bassa
Nessun parlato rilevato nell’audio
Codifica audio non supportata

{
  "code": "TRANSCRIPTION_FAILED",
  "message": "The transcription could not be completed. Please try again."
}

TRANSLATION_FAILED

Non è stato possibile tradurre la trascrizione.Possibili cause:

Coppia linguistica non supportata
Impossibile elaborare il contenuto

{
  "code": "TRANSLATION_FAILED",
  "message": "The translation could not be completed. Please try again."
}

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

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync could not be completed. Please try again."
}

Errori del server

INTERNAL_ERROR

Stato HTTP: 500Si è verificato un errore imprevisto sui nostri server.Soluzione: Riprova la richiesta. Se il problema persiste, contatta l’assistenza.

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Please try again later."
}

Gestione degli errori

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);
}

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}")

Panoramica

Discovery

Account

Utilizzo e attività

Impostazioni e notifiche

Team

Progetti

Traduzione e doppiaggio

Trascrizioni e modifica

Sintesi vocale

Voci per la sintesi vocale

Voci per il doppiaggio

Trascrizione

Sottotitoli e didascalie

Immagini

Miniature

Cartelle

Glossario

Webhook

Pubblicazione

Stato delle richieste

OAuth e protocollo MCP

Codici di errore

Codici di errore

Formato della risposta di errore

Codici di stato HTTP

Errori di trascrizione ed esportazione della trascrizione

Errori nelle opzioni di doppiaggio

Errori asincroni di allineamento SRT

Errori di autenticazione

Altri errori di autenticazione e team

Errori di convalida del file

Errori di convalida

Errori delle risorse

Errori di autorizzazione e utilizzo

Errori di elaborazione

Errori del server

Gestione degli errori

​Codici di errore

​Formato della risposta di errore

​Codici di stato HTTP

​Errori di trascrizione ed esportazione della trascrizione

​Errori nelle opzioni di doppiaggio

​Errori asincroni di allineamento SRT

​Errori di autenticazione

​Altri errori di autenticazione e team

​Errori di convalida del file

​Errori di convalida

​Errori delle risorse

​Errori di autorizzazione e utilizzo

​Errori di elaborazione

​Errori del server

​Gestione degli errori

Codici di errore

Formato della risposta di errore

Codici di stato HTTP

Errori di trascrizione ed esportazione della trascrizione

Errori nelle opzioni di doppiaggio

Errori asincroni di allineamento SRT

Errori di autenticazione

Altri errori di autenticazione e team

Errori di convalida del file

Errori di convalida

Errori delle risorse

Errori di autorizzazione e utilizzo

Errori di elaborazione

Errori del server

Gestione degli errori