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 - Het project verkeert niet in een status die het verzoek toestaat
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 - De transcriptie kon niet worden voltooid

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 kon niet worden voltooid
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	`INVALID_TRANSLATED_SRT`	translatedSrt bevat geen geldige SRT-cues
400	`TRANSLATED_SRT_CUE_COUNT_MISMATCH`	Het aantal cues van translatedSrt en sourceSrt verschilt
409	`DUB_ONLY_REQUIRES_TRANSCRIPTION`	Het project heeft geen voltooide transcriptie om te nasynchroniseren
409	`TRANSLATION_ALREADY_IN_PROGRESS`	Er loopt al een nasynchronisatie voor de taal
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`	De geselecteerde stem is geen catalogusstem of aangepaste stem die door het geauthenticeerde account is opgeslagen.
403	`LIPSYNC_MODE_ACCESS_DENIED`	Premium lipsynchronisatie-modus is niet beschikbaar in het abonnement

Asynchrone fouten bij SRT-uitlijning

Deze fouten ontstaan nadat een vertaal- of nasynchronisatieverzoek is geaccepteerd. Het statusendpoint antwoordt met HTTP 200 en status: "failed"; de bijbehorende error en de project.translation.failed-webhook bevatten alleen code en message. Opgeslagen fouten gebruiken vaste VoiceCheap-meldingen; cuenummers en segmentindexen worden niet opgenomen. Synchrone verzoekfouten, waaronder TRANSLATED_SRT_CUE_COUNT_MISMATCH, blijven HTTP 400 in de tabel hierboven.

Resultaat	Code	Betekenis
`GET` 200 / webhook	`TRANSLATED_SRT_UNMATCHED_CUES`	Een vertaalde cue komt met geen enkel transcriptsegment overeen (gemeld via status en webhooks)
`GET` 200 / webhook	`TRANSLATED_SRT_MISSING_SEGMENTS`	Een transcriptsegment heeft geen vertaalde cue (gemeld via status en webhooks)

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 opgegeven API-sleutel is ongeldig.Oplossing: Controleer of uw API-sleutel correct is en is opgenomen in de x-api-key-header.

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

SUBSCRIPTION_REQUIRED

HTTP-status: 403Toegang tot de API en MCP vereist een Starter-abonnement of hoger.Oplossing: Upgrade naar een Starter-abonnement of hoger op 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

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

Andere authenticatie- en teamfouten

HTTP	Code	Beschrijving
401	`USER_NOT_FOUND`	Het account dat bij deze sleutel hoort, is niet gevonden
403	`AMBIGUOUS_TEAM_API_KEY`	De sleutelhouder is lid van meerdere teams; neem contact op met support
403	`TEAM_OWNER_NOT_FOUND`	Het gekoppelde account van de teameigenaar is niet gevonden

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 180 minutes. Your video is 181 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."
}

Machtigings- en gebruiksfouten

Status	Code	Actie
401	`API_KEY_EXPIRED`, `INVALID_MCP_TOKEN`	Gebruik een geldige, niet-verlopen sleutel of verbind de assistent opnieuw.
403	`INSUFFICIENT_SCOPE`	Verleen de vereiste machtiging of kies andere inloggegevens.
403	`SUBSCRIPTION_REQUIRED`	Gebruik een Starter-abonnement of hoger.
429	`INTEGRATION_MONTHLY_LIMIT_REACHED`	Wacht op de maandelijkse reset of wijzig je abonnement.
429	`INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED`	Wacht voordat je het opnieuw probeert en gebruik steeds langere wachttijden.
429	`CONCURRENT_TRANSLATION_LIMIT_REACHED`	Wacht tot een lopende generatie is voltooid.
400	`VALIDATION_ERROR`	Corrigeer de argumenten aan de hand van het invoerschema in de catalogus.
404	`UNKNOWN_ACTION`	Gebruik een ondersteunde actienaam uit de ontdekking.

Zie gebruik en limieten voor het gedeelde accountquotum. Fouten gebruiken geen maandelijkse aanroepen. action_request_get, usage_get, projects_status en GET /v1/translate/{projectId}/status zijn vrijgesteld van het maandelijkse quotum.

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": "The transcription could not be completed. Please try again."
}

TRANSLATION_FAILED

De transcriptie kon niet worden vertaald.Mogelijke oorzaken:

Niet-ondersteund talenpaar
Inhoud kon niet worden verwerkt

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

LIPSYNC_FAILED

Lipsynchronisatie-verwerking mislukt.Mogelijke oorzaken:

Een tijdelijk probleem tijdens lipsynchronisatie
Ongeldige of niet-ondersteunde media
Verzoek werd afgewezen of geannuleerd

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

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

Discovery

Account

Verbruik en activiteit

Instellingen en meldingen

Team

Projecten

Vertaling en nasynchronisatie

Transcripten en bewerking

Tekst naar spraak

Spraakstemmen

Nasynchronisatiestemmen

Transcriptie

Ondertitels en captions

Afbeeldingen

Miniaturen

Mappen

Woordenlijst

Webhooks

Publiceren

Aanvraagstatus

OAuth en het MCP-protocol

Foutcodes

Foutcodes

Formaat van foutmelding

HTTP-statuscodes

Fouten bij transcriptie en transcript-export

Fouten bij nasynchronisatie-opties

Asynchrone fouten bij SRT-uitlijning

Authenticatiefouten

Andere authenticatie- en teamfouten

Bestandsvalidatiefouten

Validatiefouten

Resourcefouten

Machtigings- en gebruiksfouten

Verwerkingsfouten

Serverfouten

Fouten afhandelen

​Foutcodes

​Formaat van foutmelding

​HTTP-statuscodes

​Fouten bij transcriptie en transcript-export

​Fouten bij nasynchronisatie-opties

​Asynchrone fouten bij SRT-uitlijning

​Authenticatiefouten

​Andere authenticatie- en teamfouten

​Bestandsvalidatiefouten

​Validatiefouten

​Resourcefouten

​Machtigings- en gebruiksfouten

​Verwerkingsfouten

​Serverfouten

​Fouten afhandelen

Foutcodes

Formaat van foutmelding

HTTP-statuscodes

Fouten bij transcriptie en transcript-export

Fouten bij nasynchronisatie-opties

Asynchrone fouten bij SRT-uitlijning

Authenticatiefouten

Andere authenticatie- en teamfouten

Bestandsvalidatiefouten

Validatiefouten

Resourcefouten

Machtigings- en gebruiksfouten

Verwerkingsfouten

Serverfouten

Fouten afhandelen