Foutcodes

De VoiceCheap API gebruikt standaard HTTP-statuscodes en retourneert gestructureerde foutmeldingen om u te helpen fouten correct af te handelen.

Formaat van foutmelding

Alle foutmeldingen volgen deze structuur:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}

Sommige fouten kunnen extra velden bevatten. Validatiefouten in de request payload retourneren één item per ongeldig veld in details, en field wordt weggelaten wanneer het beperkingsbericht geen specifieke eigenschap benoemt:

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": [
    {
      "field": "outputFormat",
      "messages": ["outputFormat must be one of the following values: json, srt, vtt"]
    }
  ]
}

HTTP-statuscodes

Statuscode	Betekenis
200	OK - Verzoek geslaagd
400	Bad Request - Ongeldige parameters of validatiefout
401	Unauthorized - Ongeldige of ontbrekende API-sleutel
403	Forbidden - Geldige API-sleutel maar onvoldoende rechten
404	Not Found - Bron bestaat niet
409	Conflict - Gevraagd resultaat is nog niet gereed
413	Payload Too Large - Geüpload bestand overschrijdt de limiet
429	Too Many Requests - Snelheidslimiet overschreden
500	Internal Server Error - Er is iets misgegaan aan onze kant
502	Bad Gateway - Een verwerkingsengine is mislukt

Fouten bij transcriptie en transcript-export

Status	Code	Betekenis
400	`INVALID_MEDIA_STREAM`	Geüploade media bevat geen audiostream
400	`DURATION_TOO_LONG`	Standalone transcriptiemedia is langer dan twee uur
400	`INVALID_BRAND_VOCABULARY`	Een verzoekspecifiek woordenlijst-item overschrijdt de limieten
400	`TARGET_LANGUAGE_REQUIRED`	Een verzoek voor een vertaald transcript miste de taal
404	`TRANSCRIPT_NOT_FOUND`	Gevraagd origineel of vertaald transcript is afwezig
409	`TRANSCRIPT_NOT_READY`	Gevraagd transcript wordt nog verwerkt
502	`TRANSCRIPTION_EMPTY`	De transcriptie bevatte geen bruikbare spraak
502	`TRANSCRIPTION_FAILED`	De transcriptie-engine kon het verzoek niet voltooien
400	`INVALID_MULTIPART_REQUEST`	Het multipart-uploadverzoek is misvormd of overschrijdt de limieten

Fouten bij nasynchronisatie-opties

Status	Code	Betekenis
400	`INVALID_SOURCE_SRT`	sourceSrt bevat geen geldige SRT-cues
400	`SOURCE_LANGUAGE_REQUIRED_FOR_SRT`	sourceSrt vereist een expliciete originalLanguage
400	`VOICE_ID_REQUIRED`	Modus voor aangepaste stemmen vereist een stem-ID
400	`VOICE_ID_NOT_ALLOWED_WITH_CLONING`	voiceId werd gecombineerd met stemklonen
400	`VOICE_CLONING_SETTINGS_NOT_ALLOWED`	Klooninstellingen werden gecombineerd met modus voor aangepaste stemmen
400	`CONFLICTING_LIPSYNC_OPTIONS`	Moderne en verouderde lipsynchronisatie-velden komen niet overeen
400	`TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND`	Tijdoverslaan vereist achtergrondaudio
400	`TRANSLATION_TIME_SKIP_CONFLICT`	Tijdoverslaan conflicteert met behoud van de originele stem
400	`TRANSLATION_TIME_SKIP_OUT_OF_RANGE`	Een tijdoverslaan gaat voorbij de mediaduur
400	`INVALID_TRANSLATION_TIME_SKIPS`	Een tijdoverslaan overlapt een transcriptiesegment
400	`SUBTITLES_NOT_AVAILABLE_FOR_AUDIO`	Ingebrande ondertitels vereisen video-input
400	`LIPSYNC_NOT_AVAILABLE_FOR_AUDIO`	Lipsynchronisatie vereist video-input
400	`TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO`	Vertaaltijdoverslaan vereist video-input
403	`CUSTOM_VOICE_ACCESS_DENIED`	Aangepaste stem is niet eigendom van de effectieve eigenaar
403	`LIPSYNC_MODE_ACCESS_DENIED`	Premium lipsynchronisatie-modus is niet beschikbaar in het abonnement

Authenticatiefouten

MISSING_API_KEY

HTTP-status: 401De x-api-key-header werd niet verstrekt.Oplossing: Voeg uw API-sleutel toe in de x-api-key-header.

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

INVALID_API_KEY_FORMAT

HTTP-status: 401De API-sleutel gebruikt niet het verwachte vc_-voorvoegsel.Oplossing: Controleer of u de volledige sleutel uit de VoiceCheap-app hebt gekopieerd.

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

INVALID_API_KEY

HTTP-status: 401De verstrekte API-sleutel is ongeldig of verlopen.Oplossing: Controleer of uw API-sleutel correct is en is opgenomen in de x-api-key-header.

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

API_ACCESS_REQUIRED

HTTP-status: 403Het account heeft een geldige sleutel, maar API-toegang is niet ingeschakeld voor dat account.Oplossing: Vraag API-toegang aan of gebruik een account waarvoor API-toegang al is ingeschakeld.

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

SUBSCRIPTION_REQUIRED

HTTP-status: 403API-toegang vereist een actief betaald abonnement.Oplossing: Upgrade naar een betaald abonnement op voicecheap.ai.

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

INSUFFICIENT_CREDITS

HTTP-status: 403Uw account heeft onvoldoende credits om dit verzoek te verwerken.Oplossing: Koop meer credits of upgrade uw abonnement.

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits to process this file. Please add more credits to your account."
}

Bestandsvalidatiefouten

FILE_REQUIRED

HTTP-status: 400Er is geen bestand geüpload bij het verzoek.Oplossing: Voeg een bestand toe in het file-veld van uw multipart-formuliergegevens.

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

INVALID_FILE_TYPE

HTTP-status: 400Het geüploade bestandstype wordt niet ondersteund.Oplossing: Upload een bestand in een van de ondersteunde formaten (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

HTTP-status: 413Het geüploade bestand overschrijdt de limiet voor het geauthenticeerde abonnement: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB of Enterprise 60 GB.Oplossing: Controleer uw abonnementslimiet en comprimeer vervolgens het bestand, splits het in kleinere segmenten of upgrade uw abonnement.

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

DURATION_DETECTION_FAILED

HTTP-status: 400De duur van het geüploade bestand kon niet worden gedetecteerd.Oplossing: Zorg ervoor dat het bestand een geldig, niet-beschadigd video- of audiobestand is.

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

Validatiefouten

INVALID_TARGET_LANGUAGE

HTTP-status: 400De opgegeven doeltaal wordt niet ondersteund.Oplossing: Gebruik een van de ondersteunde talen.

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

INVALID_BOOLEAN_VALUE

HTTP-status: 400Een booleaanse parameter heeft een ongeldige waarde ontvangen.Oplossing: Gebruik true of false (als strings in form-data).

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

INVALID_JSON_FORMAT

HTTP-status: 400Een JSON-parameter kon niet worden geparseerd.Oplossing: Zorg ervoor dat de JSON-string correct is geformatteerd.

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

INVALID_NUMBER_VALUE

HTTP-status: 400Een optioneel numeriek form-data-veld was geen geldig getal. Stuur een numerieke waarde binnen het gedocumenteerde bereik.

LIPSYNC_VIDEO_TOO_LONG

HTTP-status: 400Lipsynchronisatie werd aangevraagd voor media die langer is dan de ondersteunde duur voor lipsynchronisatie.Oplossing: Laat lipsyncPro weg voor dit verzoek, of dien een mediabestand in binnen de limiet voor lipsynchronisatie.

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

Resourcefouten

PROJECT_NOT_FOUND

HTTP-status: 404Het opgegeven project bestaat niet.Oplossing: Controleer of de project-ID correct is.

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

FORBIDDEN

HTTP-status: 403Je hebt geen toestemming om toegang te krijgen tot deze resource.Oplossing: Zorg ervoor dat je de juiste API-sleutel voor dit project gebruikt.

{
  "code": "FORBIDDEN",
  "message": "You do not have permission to access this project."
}

Snelheidsbeperking

RATE_LIMIT_EXCEEDED

HTTP-status: 429Je hebt de snelheidslimiet voor dit eindpunt overschreden.Oplossing: Wacht voordat je extra verzoeken doet. Gebruik exponentiële back-off.

Eindpunt	Snelheidslimiet
`POST /v1/translate`	10 verzoeken per minuut
`POST /v1/projects`	10 verzoeken per minuut
`GET /v1/translate/{id}/status`	30 verzoeken per minuut
`GET /v1/projects/{id}`	20 verzoeken per minuut
`DELETE /v1/translate/{id}`	10 verzoeken per minuut

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

CONCURRENT_TRANSLATION_LIMIT_REACHED

HTTP-status: 429Je hebt al het maximale aantal vertalingen dat parallel draait.Oplossing: Wacht tot een van je lopende vertalingen is voltooid en probeer het verzoek opnieuw.

{
  "code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
  "message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
}

Verwerkingsfouten

Deze fouten kunnen worden geretourneerd in het error-veld bij het controleren van de vertaalstatus:

TRANSCRIPTION_FAILED

De audio kon niet worden getranscribeerd.Mogelijke oorzaken:

Audiokwaliteit is te laag
Geen spraak gedetecteerd in de audio
Niet-ondersteunde audio-encodering

{
  "code": "TRANSCRIPTION_FAILED",
  "message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}

TRANSLATION_FAILED

De transcriptie kon niet worden vertaald.Mogelijke oorzaken:

Niet-ondersteund talenpaar
Inhoud kon niet worden verwerkt

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

VOICE_SYNTHESIS_FAILED

Stem-synthese mislukt tijdens nasynchronisatie.Mogelijke oorzaken:

Stemklonen mislukt
Fout bij het genereren van audio

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

LIPSYNC_FAILED

Lipsynchronisatie-verwerking mislukt.Mogelijke oorzaken:

Fout bij lipsynchronisatie-provider
Ongeldige of niet-ondersteunde media
Verzoek werd afgewezen of geannuleerd

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

Serverfouten

INTERNAL_ERROR

HTTP-status: 500Er is een onverwachte fout opgetreden op onze servers.Oplossing: Probeer het verzoek opnieuw. Als het probleem aanhoudt, neem dan contact op met de ondersteuning.

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

Fouten afhandelen

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

Overzicht

Transcriptie

Vertaling

Referentie

Foutcodes

Foutcodes

Formaat van foutmelding

HTTP-statuscodes

Fouten bij transcriptie en transcript-export

Fouten bij nasynchronisatie-opties

Authenticatiefouten

Bestandsvalidatiefouten

Validatiefouten

Resourcefouten

Snelheidsbeperking

Verwerkingsfouten

Serverfouten

Fouten afhandelen

​Foutcodes

​Formaat van foutmelding

​HTTP-statuscodes

​Fouten bij transcriptie en transcript-export

​Fouten bij nasynchronisatie-opties

​Authenticatiefouten

​Bestandsvalidatiefouten

​Validatiefouten

​Resourcefouten

​Snelheidsbeperking

​Verwerkingsfouten

​Serverfouten

​Fouten afhandelen

Foutcodes

Formaat van foutmelding

HTTP-statuscodes

Fouten bij transcriptie en transcript-export

Fouten bij nasynchronisatie-opties

Authenticatiefouten

Bestandsvalidatiefouten

Validatiefouten

Resourcefouten

Snelheidsbeperking

Verwerkingsfouten

Serverfouten

Fouten afhandelen