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

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 o è scaduta.Soluzione: Verifica che la tua chiave API sia corretta e inclusa nell’intestazione x-api-key.

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid. Please check your API key and try again."
}

API_ACCESS_REQUIRED

Stato HTTP: 403L’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.

{
  "code": "API_ACCESS_REQUIRED",
  "message": "API access is required. Please request access to the API beta program."
}

SUBSCRIPTION_REQUIRED

Stato HTTP: 403L’accesso all’API richiede un abbonamento a pagamento attivo.Soluzione: Passa a un piano a pagamento su voicecheap.ai.

{
  "code": "SUBSCRIPTION_REQUIRED",
  "message": "API access requires an active paid subscription. Please upgrade your plan."
}

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

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 30 minutes. Your video is 45 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."
}

Limitazione della frequenza

RATE_LIMIT_EXCEEDED

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

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait before trying again."
}

CONCURRENT_TRANSLATION_LIMIT_REACHED

Stato HTTP: 429Si 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.

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

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": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}

TRANSLATION_FAILED

Non è stato possibile tradurre la trascrizione.Possibili cause:

Coppia linguistica non supportata
Impossibile elaborare il contenuto

{
  "code": "TRANSLATION_FAILED",
  "message": "Failed to translate the content. Please try again."
}

VOICE_SYNTHESIS_FAILED

La sintesi vocale non è riuscita durante il doppiaggio.Possibili cause:

La clonazione vocale non è riuscita
Errore di generazione audio

{
  "code": "VOICE_SYNTHESIS_FAILED",
  "message": "Failed to generate the dubbed audio. Please try again."
}

LIPSYNC_FAILED

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

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync failed."
}

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

Trascrizione

Traduzione

Riferimento

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 di autenticazione

Errori di convalida del file

Errori di convalida

Errori delle risorse

Limitazione della frequenza

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 di autenticazione

​Errori di convalida del file

​Errori di convalida

​Errori delle risorse

​Limitazione della frequenza

​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 di autenticazione

Errori di convalida del file

Errori di convalida

Errori delle risorse

Limitazione della frequenza

Errori di elaborazione

Errori del server

Gestione degli errori