> ## 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** - Angefordertes Ergebnis ist nicht bereit | | 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** - Eine Verarbeitungseinheit ist fehlgeschlagen | ## 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 Transkriptions-Engine konnte die Anfrage nicht abschließen | | 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 | `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 benutzerdefinierte Stimme gehört nicht dem effektiven Eigentümer | | 403 | `LIPSYNC_MODE_ACCESS_DENIED` | Der Premium-Modus für Lippensynchronisation ist in diesem Plan nicht verfügbar | ## Authentifizierungsfehler **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." } ``` **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_\"." } ``` **HTTP-Status:** 401 Der bereitgestellte API-Schlüssel ist ungültig oder abgelaufen. **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": "The provided API key is invalid. Please check your API key and try again." } ``` **HTTP-Status:** 403 Das Konto verfügt über einen gültigen Schlüssel, aber der API-Zugriff ist für dieses Konto nicht aktiviert. **Lösung:** Beantragen Sie den API-Zugriff oder verwenden Sie ein Konto, für das der API-Zugriff bereits aktiviert ist. ```json theme={null} { "code": "API_ACCESS_REQUIRED", "message": "API access is required. Please request access to the API beta program." } ``` **HTTP-Status:** 403 Der API-Zugriff erfordert ein aktives kostenpflichtiges Abonnement. **Lösung:** Führen Sie ein Upgrade auf einen kostenpflichtigen Plan unter [voicecheap.ai](https://voicecheap.ai/pricing) durch. ```json theme={null} { "code": "SUBSCRIPTION_REQUIRED", "message": "API access requires an active paid subscription. Please upgrade your plan." } ``` **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." } ``` ## Fehler bei der Dateiüberprüfung **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." } ``` **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, ..." } ``` **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 } ``` **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 **HTTP-Status:** 400 Die angegebene Zielsprache wird nicht unterstützt. **Lösung:** Verwenden Sie eine der [unterstützte Sprachen](/docs/de/introduction#supported-languages). ```json theme={null} { "code": "VALIDATION_ERROR", "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..." } ``` **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\"." } ``` **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." } ``` **HTTP-Status:** 400 Ein optionales numerisches form-data-Feld war keine gültige Zahl. Senden Sie einen numerischen Wert innerhalb des dokumentierten Bereichs. **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 30 minutes. Your video is 45 minutes long." } ``` ## Ressourcenfehler **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." } ``` **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." } ``` ## Ratenbegrenzung **HTTP-Status:** 429 Sie haben die Ratenbegrenzung für diesen Endpunkt überschritten. **Lösung:** Warten Sie, bevor Sie weitere Anfragen stellen. Verwenden Sie exponentielles Backoff. | Endpunkt | Ratenbegrenzung | | ------------------------------- | ---------------------- | | `POST /v1/translate` | 10 Anfragen pro Minute | | `POST /v1/projects` | 10 Anfragen pro Minute | | `GET /v1/translate/{id}/status` | 30 Anfragen pro Minute | | `GET /v1/projects/{id}` | 20 Anfragen pro Minute | | `DELETE /v1/translate/{id}` | 10 Anfragen pro Minute | ```json theme={null} { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please wait before trying again." } ``` **HTTP-Status:** 429 Sie haben bereits die maximale Anzahl an parallel laufenden Übersetzungen erreicht. **Lösung:** Warten Sie, bis eine Ihrer laufenden Übersetzungen abgeschlossen ist, und wiederholen Sie dann die Anfrage. ```json theme={null} { "code": "CONCURRENT_TRANSLATION_LIMIT_REACHED", "message": "Concurrent translation limit reached. You can run up to 10 translations at the same time." } ``` ## Verarbeitungsfehler Diese Fehler können im Feld `error` zurückgegeben werden, wenn der Übersetzungsstatus überprüft wird: 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": "Could not transcribe the audio. Please ensure the audio quality is sufficient." } ``` 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": "Failed to translate the content. Please try again." } ``` Die Sprachsynthese schlug während der Synchronisation fehl. **Mögliche Ursachen:** * Stimmklonen fehlgeschlagen * Fehler bei der Audiogenerierung ```json theme={null} { "code": "VOICE_SYNTHESIS_FAILED", "message": "Failed to generate the dubbed audio. Please try again." } ``` Die Verarbeitung der Lippensynchronisation schlug fehl. **Mögliche Ursachen:** * Fehler beim Anbieter für Lippensynchronisation * Ungültige oder nicht unterstützte Medien * Anfrage wurde abgelehnt oder storniert ```json theme={null} { "code": "LIPSYNC_FAILED", "message": "Lip sync failed." } ``` ## Serverfehler **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}") ```