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

# Foutcodes

> Volledige referentie van foutcodes geretourneerd door de VoiceCheap API

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

```json theme={null}
{
  "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:

```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"]
    }
  ]
}
```

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

> [accordion] MISSING\_API\_KEY
>
> **HTTP-status:** 401
>
> De `x-api-key`-header werd niet verstrekt.
>
> **Oplossing:** Voeg uw API-sleutel toe in de `x-api-key`-header.
>
> ```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
>
> **HTTP-status:** 401
>
> De API-sleutel gebruikt niet het verwachte `vc_`-voorvoegsel.
>
> **Oplossing:** Controleer of u de volledige sleutel uit de VoiceCheap-app hebt gekopieerd.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY_FORMAT",
>   "message": "Invalid API key format. API keys must start with \"vc_\"."
> }
> ```

> [accordion] INVALID\_API\_KEY
>
> **HTTP-status:** 401
>
> De opgegeven API-sleutel is ongeldig.
>
> **Oplossing:** Controleer of uw API-sleutel correct is en is opgenomen in de `x-api-key`-header.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY",
>   "message": "Invalid API key. Please check your API key and try again."
> }
> ```

> [accordion] SUBSCRIPTION\_REQUIRED
>
> **HTTP-status:** 403
>
> Toegang tot de API en MCP vereist een Starter-abonnement of hoger.
>
> **Oplossing:** Upgrade naar een Starter-abonnement of hoger op [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
>
> **HTTP-status:** 403
>
> Uw account heeft onvoldoende credits om dit verzoek te verwerken.
>
> **Oplossing:** Koop meer credits of upgrade uw abonnement.
>
> ```json theme={null}
> {
>   "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

> [accordion] FILE\_REQUIRED
>
> **HTTP-status:** 400
>
> Er is geen bestand geüpload bij het verzoek.
>
> **Oplossing:** Voeg een bestand toe in het `file`-veld van uw multipart-formuliergegevens.
>
> ```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
>
> **HTTP-status:** 400
>
> Het 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).
>
> ```json theme={null}
> {
>   "code": "INVALID_FILE_TYPE",
>   "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
> }
> ```

> [accordion] FILE\_TOO\_LARGE
>
> **HTTP-status:** 413
>
> Het 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.
>
> ```json theme={null}
> {
>   "code": "FILE_TOO_LARGE",
>   "message": "File size exceeds the 5GB limit for the beginner plan.",
>   "maximumFileSizeBytes": 5368709120
> }
> ```

> [accordion] DURATION\_DETECTION\_FAILED
>
> **HTTP-status:** 400
>
> De duur van het geüploade bestand kon niet worden gedetecteerd.
>
> **Oplossing:** Zorg ervoor dat het bestand een geldig, niet-beschadigd video- of audiobestand is.
>
> ```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."
> }
> ```

## Validatiefouten

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **HTTP-status:** 400
>
> De opgegeven doeltaal wordt niet ondersteund.
>
> **Oplossing:** Gebruik een van de [ondersteunde talen](https://api-docs.voicecheap.ai/docs/nl/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
>
> **HTTP-status:** 400
>
> Een booleaanse parameter heeft een ongeldige waarde ontvangen.
>
> **Oplossing:** Gebruik `true` of `false` (als strings 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
>
> **HTTP-status:** 400
>
> Een JSON-parameter kon niet worden geparseerd.
>
> **Oplossing:** Zorg ervoor dat de JSON-string correct is geformatteerd.
>
> ```json theme={null}
> {
>   "code": "INVALID_JSON_FORMAT",
>   "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **HTTP-status:** 400
>
> Een optioneel numeriek form-data-veld was geen geldig getal. Stuur een numerieke waarde binnen het gedocumenteerde bereik.

> [accordion] LIPSYNC\_VIDEO\_TOO\_LONG
>
> **HTTP-status:** 400
>
> Lipsynchronisatie 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.
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_VIDEO_TOO_LONG",
>   "message": "LipSync supports up to 180 minutes. Your video is 181 minutes long."
> }
> ```

## Resourcefouten

> [accordion] PROJECT\_NOT\_FOUND
>
> **HTTP-status:** 404
>
> Het opgegeven project bestaat niet.
>
> **Oplossing:** Controleer of de project-ID correct is.
>
> ```json theme={null}
> {
>   "code": "PROJECT_NOT_FOUND",
>   "message": "Project with ID 'abc123' not found."
> }
> ```

> [accordion] FORBIDDEN
>
> **HTTP-status:** 403
>
> Je hebt geen toestemming om toegang te krijgen tot deze resource.
>
> **Oplossing:** Zorg ervoor dat je de juiste API-sleutel voor dit project gebruikt.
>
> ```json theme={null}
> {
>   "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](https://api-docs.voicecheap.ai/docs/nl/api-reference/limits.md) 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:

> [accordion] TRANSCRIPTION\_FAILED
>
> De audio kon niet worden getranscribeerd.
>
> **Mogelijke oorzaken:**
>
> * Audiokwaliteit is te laag
> * Geen spraak gedetecteerd in de audio
> * Niet-ondersteunde audio-encodering
>
> ```json theme={null}
> {
>   "code": "TRANSCRIPTION_FAILED",
>   "message": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] TRANSLATION\_FAILED
>
> De transcriptie kon niet worden vertaald.
>
> **Mogelijke oorzaken:**
>
> * Niet-ondersteund talenpaar
> * Inhoud kon niet worden verwerkt
>
> ```json theme={null}
> {
>   "code": "TRANSLATION_FAILED",
>   "message": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] LIPSYNC\_FAILED
>
> Lipsynchronisatie-verwerking mislukt.
>
> **Mogelijke oorzaken:**
>
> * Een tijdelijk probleem tijdens lipsynchronisatie
> * Ongeldige of niet-ondersteunde media
> * Verzoek werd afgewezen of geannuleerd
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## Serverfouten

> [accordion] INTERNAL\_ERROR
>
> **HTTP-status:** 500
>
> Er is een onverwachte fout opgetreden op onze servers.
>
> **Oplossing:** Probeer het verzoek opnieuw. Als het probleem aanhoudt, neem dan contact op met de ondersteuning.
>
> ```json theme={null}
> {
>   "code": "INTERNAL_ERROR",
>   "message": "An unexpected error occurred. Please try again later."
> }
> ```

## Fouten afhandelen

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