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

# Fehlercodes

> Vollständige Referenz der Fehlercodes, die von der VoiceCheap API zurückgegeben werden

# Fehlercodes

Die VoiceCheap API verwendet Standard-HTTP-Statuscodes und gibt strukturierte Fehlerantworten zurück, damit Sie Fehler elegant behandeln können.

## Format der Fehlerantwort

Alle Fehlerantworten folgen dieser Struktur:

```json theme={null}
{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}
```

Einige Fehler können zusätzliche Felder enthalten. Validierungsfehler bei der Anfrage-Payload geben einen Eintrag pro
ungültigem Feld in `details` zurück, und `field` wird weggelassen, wenn die Constraint-Meldung keine
spezifische Eigenschaft benennt:

```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 | Bedeutung |
| - | - |
| 200 | **OK** - Anfrage erfolgreich |
| 400 | **Bad Request** - Ungültige Parameter oder Validierungsfehler |
| 401 | **Unauthorized** - Ungültiger oder fehlender API-Schlüssel |
| 403 | **Forbidden** - Gültiger API-Schlüssel, aber unzureichende Berechtigungen |
| 404 | **Not Found** - Ressource existiert nicht |
| 409 | **Conflict** - Das Projekt befindet sich nicht in einem Zustand, der die Anfrage zulässt |
| 413 | **Payload Too Large** - Hochgeladene Datei überschreitet ihr Limit |
| 429 | **Too Many Requests** - Ratenlimit überschritten |
| 500 | **Internal Server Error** - Etwas ist auf unserer Seite schiefgelaufen |
| 502 | **Bad Gateway** - Die Transkription konnte nicht abgeschlossen werden |

## Fehler bei Transkription und Transkriptexport

| Status | Code | Bedeutung |
| - | - | - |
| 400 | `INVALID_MEDIA_STREAM` | Hochgeladene Medien enthalten keinen Audiostream |
| 400 | `DURATION_TOO_LONG` | Eigenständige Transkriptionsmedien sind länger als zwei Stunden |
| 400 | `INVALID_BRAND_VOCABULARY` | Ein anfragespezifischer Glossar-Eintrag verletzt die Grenzwerte |
| 400 | `TARGET_LANGUAGE_REQUIRED` | Eine Anfrage für ein übersetztes Transkript hat die Sprache weggelassen |
| 404 | `TRANSCRIPT_NOT_FOUND` | Das angeforderte Original- oder übersetzte Transkript fehlt |
| 409 | `TRANSCRIPT_NOT_READY` | Das angeforderte Transkript wird noch verarbeitet |
| 502 | `TRANSCRIPTION_EMPTY` | Die Transkription enthielt keine verwertbare Sprache |
| 502 | `TRANSCRIPTION_FAILED` | Die Transkription konnte nicht abgeschlossen werden |
| 400 | `INVALID_MULTIPART_REQUEST` | Die Multipart-Upload-Anfrage ist fehlerhaft oder überschreitet Grenzwerte |

## Fehler bei Synchronisationsoptionen

| Status | Code | Bedeutung |
| - | - | - |
| 400 | `INVALID_SOURCE_SRT` | sourceSrt enthält keine gültigen SRT-Cues |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt erfordert eine explizite originalLanguage |
| 400 | `INVALID_TRANSLATED_SRT` | translatedSrt enthält keine gültigen SRT-Cues |
| 400 | `TRANSLATED_SRT_CUE_COUNT_MISMATCH` | Die Cue-Anzahl von translatedSrt und sourceSrt unterscheidet sich |
| 409 | `DUB_ONLY_REQUIRES_TRANSCRIPTION` | Das Projekt hat keine abgeschlossene Transkription zum Synchronisieren |
| 409 | `TRANSLATION_ALREADY_IN_PROGRESS` | Für die Sprache läuft bereits eine Synchronisation |
| 400 | `VOICE_ID_REQUIRED` | Der Modus für benutzerdefinierte Stimmen erfordert eine Stimmen-ID |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | voiceId wurde mit Stimmklonen kombiniert |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Klon-Einstellungen wurden mit dem Modus für benutzerdefinierte Stimmen kombiniert |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | Moderne und Legacy-Felder für Lippensynchronisation stimmen nicht überein |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | Zeitübersprünge erfordern Hintergrundaudio |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | Zeitübersprünge stehen im Konflikt mit der Beibehaltung der Originalstimme |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Ein Zeitübersprung geht über die Mediendauer hinaus |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Ein Zeitübersprung überschneidet sich mit einem Transkriptionssegment |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Eingebrannte Untertitel erfordern Videoeingabe |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | Lippensynchronisation erfordert Videoeingabe |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Übersetzungs-Zeitübersprünge erfordern Videoeingabe |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | Die ausgewählte Stimme ist weder eine Katalogstimme noch eine vom authentifizierten Konto gespeicherte benutzerdefinierte Stimme. |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | Der Premium-Modus für Lippensynchronisation ist in diesem Plan nicht verfügbar |

## Asynchrone SRT-Ausrichtungsfehler

Diese Fehler treten auf, nachdem eine Übersetzungs- oder Vertonungsanfrage angenommen wurde. Der Status-Endpunkt antwortet mit HTTP 200 und `status: "failed"`; sein `error` und der Webhook `project.translation.failed` enthalten nur `code` und `message`. Gespeicherte Fehler verwenden feste VoiceCheap-Meldungen; Cue-Nummern und Segmentindizes sind nicht enthalten. Synchrone Anforderungsfehler wie `TRANSLATED_SRT_CUE_COUNT_MISMATCH` bleiben oben als HTTP 400 aufgeführt.

| Ergebnis | Code | Bedeutung |
| - | - | - |
| `GET` 200 / webhook | `TRANSLATED_SRT_UNMATCHED_CUES` | Ein übersetzter Cue passt zu keinem Transkriptsegment (gemeldet über Status und Webhooks) |
| `GET` 200 / webhook | `TRANSLATED_SRT_MISSING_SEGMENTS` | Ein Transkriptsegment hat keinen übersetzten Cue (gemeldet über Status und Webhooks) |

## Authentifizierungsfehler

> [accordion] MISSING\_API\_KEY
>
> **HTTP-Status:** 401
>
> Der `x-api-key`-Header wurde nicht bereitgestellt.
>
> **Lösung:** Fügen Sie Ihren API-Schlüssel in den `x-api-key`-Header ein.
>
> ```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
>
> Der API-Schlüssel verwendet nicht das erwartete `vc_`-Präfix.
>
> **Lösung:** Überprüfen Sie, ob Sie den vollständigen Schlüssel aus der VoiceCheap-App kopiert haben.
>
> ```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
>
> Der angegebene API-Schlüssel ist ungültig.
>
> **Lösung:** Überprüfen Sie, ob Ihr API-Schlüssel korrekt ist und im `x-api-key`-Header enthalten ist.
>
> ```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
>
> Der Zugriff auf API und MCP erfordert einen Starter-Plan oder höher.
>
> **Lösung:** Führen Sie ein Upgrade auf einen Starter-Plan oder höher unter [voicecheap.ai](https://voicecheap.ai/pricing) durch.
>
> ```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
>
> Ihr Konto verfügt nicht über genügend Guthaben, um diese Anfrage zu verarbeiten.
>
> **Lösung:** Kaufen Sie mehr Guthaben oder führen Sie ein Upgrade Ihres Abonnementplans durch.
>
> ```json theme={null}
> {
>   "code": "INSUFFICIENT_CREDITS",
>   "message": "Insufficient credits to process this file. Please add more credits to your account."
> }
> ```

## Weitere Authentifizierungs- und Teamfehler

| HTTP | Code | Beschreibung |
| - | - | - |
| 401 | `USER_NOT_FOUND` | Das mit diesem Schlüssel verknüpfte Konto wurde nicht gefunden |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | Der Schlüsselinhaber gehört mehreren Teams an; kontaktieren Sie den Support |
| 403 | `TEAM_OWNER_NOT_FOUND` | Das verknüpfte Konto des Teambesitzers wurde nicht gefunden |

## Fehler bei der Dateiüberprüfung

> [accordion] FILE\_REQUIRED
>
> **HTTP-Status:** 400
>
> Mit der Anfrage wurde keine Datei hochgeladen.
>
> **Lösung:** Fügen Sie eine Datei in das `file`-Feld Ihrer Multipart-Formulardaten ein.
>
> ```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
>
> Der hochgeladene Dateityp wird nicht unterstützt.
>
> **Lösung:** Laden Sie eine Datei in einem der unterstützten Formate hoch (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
>
> Die hochgeladene Datei überschreitet das zulässige Limit für das authentifizierte Abonnement: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB oder Enterprise 60 GB.
>
> **Lösung:** Überprüfen Sie Ihr Plan-Limit, komprimieren Sie die Datei, teilen Sie sie in kleinere Segmente auf oder führen Sie ein Upgrade Ihres Plans durch.
>
> ```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
>
> Die Dauer der hochgeladenen Datei konnte nicht erkannt werden.
>
> **Lösung:** Stellen Sie sicher, dass es sich bei der Datei um eine gültige, nicht beschädigte Video- oder Audiodatei handelt.
>
> ```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."
> }
> ```

## Validierungsfehler

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **HTTP-Status:** 400
>
> Die angegebene Zielsprache wird nicht unterstützt.
>
> **Lösung:** Verwenden Sie eine der [unterstützte Sprachen](https://api-docs.voicecheap.ai/docs/de/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
>
> Ein boolescher Parameter hat einen ungültigen Wert erhalten.
>
> **Lösung:** Verwenden Sie `true` oder `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
>
> Ein JSON-Parameter konnte nicht geparst werden.
>
> **Lösung:** Stellen Sie sicher, dass der JSON-String korrekt formatiert ist.
>
> ```json theme={null}
> {
>   "code": "INVALID_JSON_FORMAT",
>   "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **HTTP-Status:** 400
>
> Ein optionales numerisches form-data-Feld war keine gültige Zahl. Senden Sie einen numerischen Wert innerhalb des dokumentierten Bereichs.

> [accordion] LIPSYNC\_VIDEO\_TOO\_LONG
>
> **HTTP-Status:** 400
>
> Lippensynchronisation wurde für Medien angefordert, die länger als die unterstützte Dauer für Lippensynchronisation sind.
>
> **Lösung:** Lassen Sie `lipsyncPro` für diese Anfrage weg oder senden Sie eine Mediendatei innerhalb des Limits für Lippensynchronisation.
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_VIDEO_TOO_LONG",
>   "message": "LipSync supports up to 180 minutes. Your video is 181 minutes long."
> }
> ```

## Ressourcenfehler

> [accordion] PROJECT\_NOT\_FOUND
>
> **HTTP-Status:** 404
>
> Das angegebene Projekt existiert nicht.
>
> **Lösung:** Überprüfen Sie, ob die Projekt-ID korrekt ist.
>
> ```json theme={null}
> {
>   "code": "PROJECT_NOT_FOUND",
>   "message": "Project with ID 'abc123' not found."
> }
> ```

> [accordion] FORBIDDEN
>
> **HTTP-Status:** 403
>
> Sie haben keine Berechtigung, auf diese Ressource zuzugreifen.
>
> **Lösung:** Stellen Sie sicher, dass Sie den korrekten API-Schlüssel für dieses Projekt verwenden.
>
> ```json theme={null}
> {
>   "code": "FORBIDDEN",
>   "message": "You do not have permission to access this project."
> }
> ```

## Berechtigungs- und Nutzungsfehler

| Status | Code | Aktion |
| - | - | - |
| 401 | `API_KEY_EXPIRED`, `INVALID_MCP_TOKEN` | Verwenden Sie einen gültigen, nicht abgelaufenen Schlüssel oder verbinden Sie den Assistenten erneut. |
| 403 | `INSUFFICIENT_SCOPE` | Erteilen Sie die erforderliche Berechtigung oder wählen Sie andere Zugangsdaten. |
| 403 | `SUBSCRIPTION_REQUIRED` | Verwenden Sie einen Starter-Plan oder höher. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Warten Sie auf die monatliche Zurücksetzung oder wechseln Sie den Tarif. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED` | Warten Sie vor einem erneuten Versuch und verlängern Sie die Wartezeiten schrittweise. |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Warten Sie, bis eine laufende Generierung abgeschlossen ist. |
| 400 | `VALIDATION_ERROR` | Korrigieren Sie die Argumente anhand des Eingabeschemas im Katalog. |
| 404 | `UNKNOWN_ACTION` | Verwenden Sie einen unterstützten Aktionsnamen aus der Erkennung. |

Das gemeinsame Kontokontingent finden Sie unter [Nutzung und Limits](https://api-docs.voicecheap.ai/docs/de/api-reference/limits.md). Fehler verbrauchen keine monatlichen Aufrufe. `action_request_get`, `usage_get`, `projects_status` und `GET /v1/translate/{projectId}/status` sind vom monatlichen Kontingent ausgenommen.

## Verarbeitungsfehler

Diese Fehler können im Feld `error` zurückgegeben werden, wenn der Übersetzungsstatus überprüft wird:

> [accordion] TRANSCRIPTION\_FAILED
>
> Das Audio konnte nicht transkribiert werden.
>
> **Mögliche Ursachen:**
>
> * Audioqualität ist zu niedrig
> * Keine Sprache im Audio erkannt
> * Nicht unterstützte Audiokodierung
>
> ```json theme={null}
> {
>   "code": "TRANSCRIPTION_FAILED",
>   "message": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] TRANSLATION\_FAILED
>
> Die Transkription konnte nicht übersetzt werden.
>
> **Mögliche Ursachen:**
>
> * Nicht unterstütztes Sprachpaar
> * Inhalt konnte nicht verarbeitet werden
>
> ```json theme={null}
> {
>   "code": "TRANSLATION_FAILED",
>   "message": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] LIPSYNC\_FAILED
>
> Die Verarbeitung der Lippensynchronisation schlug fehl.
>
> **Mögliche Ursachen:**
>
> * Ein vorübergehender Fehler bei der Lippensynchronisation
> * Ungültige oder nicht unterstützte Medien
> * Anfrage wurde abgelehnt oder storniert
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## Serverfehler

> [accordion] INTERNAL\_ERROR
>
> **HTTP-Status:** 500
>
> Ein unerwarteter Fehler ist auf unseren Servern aufgetreten.
>
> **Lösung:** Wiederholen Sie die Anfrage. Wenn das Problem weiterhin besteht, kontaktieren Sie den Support.
>
> ```json theme={null}
> {
>   "code": "INTERNAL_ERROR",
>   "message": "An unexpected error occurred. Please try again later."
> }
> ```

## Fehlerbehandlung

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