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:

{
  "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:

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

MISSING_API_KEY

HTTP-Status: 401Der x-api-key-Header wurde nicht bereitgestellt.Lösung: Fügen Sie Ihren API-Schlüssel in den x-api-key-Header ein.

{
  "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: 401Der 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.

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

INVALID_API_KEY

HTTP-Status: 401Der 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.

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

API_ACCESS_REQUIRED

HTTP-Status: 403Das 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.

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

SUBSCRIPTION_REQUIRED

HTTP-Status: 403Der API-Zugriff erfordert ein aktives kostenpflichtiges Abonnement.Lösung: Führen Sie ein Upgrade auf einen kostenpflichtigen Plan unter voicecheap.ai durch.

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

INSUFFICIENT_CREDITS

HTTP-Status: 403Ihr 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.

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

Fehler bei der Dateiüberprüfung

FILE_REQUIRED

HTTP-Status: 400Mit der Anfrage wurde keine Datei hochgeladen.Lösung: Fügen Sie eine Datei in das file-Feld Ihrer Multipart-Formulardaten ein.

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

INVALID_FILE_TYPE

HTTP-Status: 400Der 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).

{
  "code": "INVALID_FILE_TYPE",
  "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
}

FILE_TOO_LARGE

HTTP-Status: 413Die 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.

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

DURATION_DETECTION_FAILED

HTTP-Status: 400Die 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.

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

INVALID_TARGET_LANGUAGE

HTTP-Status: 400Die angegebene Zielsprache wird nicht unterstützt.Lösung: Verwenden Sie eine der unterstützte Sprachen.

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

INVALID_BOOLEAN_VALUE

HTTP-Status: 400Ein boolescher Parameter hat einen ungültigen Wert erhalten.Lösung: Verwenden Sie true oder 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: 400Ein JSON-Parameter konnte nicht geparst werden.Lösung: Stellen Sie sicher, dass der JSON-String korrekt formatiert ist.

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

INVALID_NUMBER_VALUE

HTTP-Status: 400Ein optionales numerisches form-data-Feld war keine gültige Zahl. Senden Sie einen numerischen Wert innerhalb des dokumentierten Bereichs.

LIPSYNC_VIDEO_TOO_LONG

HTTP-Status: 400Lippensynchronisation 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.

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

Ressourcenfehler

PROJECT_NOT_FOUND

HTTP-Status: 404Das angegebene Projekt existiert nicht.Lösung: Überprüfen Sie, ob die Projekt-ID korrekt ist.

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

FORBIDDEN

HTTP-Status: 403Sie haben keine Berechtigung, auf diese Ressource zuzugreifen.Lösung: Stellen Sie sicher, dass Sie den korrekten API-Schlüssel für dieses Projekt verwenden.

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

Ratenbegrenzung

RATE_LIMIT_EXCEEDED

HTTP-Status: 429Sie 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

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

CONCURRENT_TRANSLATION_LIMIT_REACHED

HTTP-Status: 429Sie 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.

{
  "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:

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

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

TRANSLATION_FAILED

Die Transkription konnte nicht übersetzt werden.Mögliche Ursachen:

Nicht unterstütztes Sprachpaar
Inhalt konnte nicht verarbeitet werden

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

VOICE_SYNTHESIS_FAILED

Die Sprachsynthese schlug während der Synchronisation fehl.Mögliche Ursachen:

Stimmklonen fehlgeschlagen
Fehler bei der Audiogenerierung

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

LIPSYNC_FAILED

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

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

Serverfehler

INTERNAL_ERROR

HTTP-Status: 500Ein unerwarteter Fehler ist auf unseren Servern aufgetreten.Lösung: Wiederholen Sie die Anfrage. Wenn das Problem weiterhin besteht, kontaktieren Sie den Support.

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

Fehlerbehandlung

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

Überblick

Transkription

Übersetzung

Referenz

Fehlercodes

Fehlercodes

Format der Fehlerantwort

HTTP-Statuscodes

Fehler bei Transkription und Transkriptexport

Fehler bei Synchronisationsoptionen

Authentifizierungsfehler

Fehler bei der Dateiüberprüfung

Validierungsfehler

Ressourcenfehler

Ratenbegrenzung

Verarbeitungsfehler

Serverfehler

Fehlerbehandlung

​Fehlercodes

​Format der Fehlerantwort

​HTTP-Statuscodes

​Fehler bei Transkription und Transkriptexport

​Fehler bei Synchronisationsoptionen

​Authentifizierungsfehler

​Fehler bei der Dateiüberprüfung

​Validierungsfehler

​Ressourcenfehler

​Ratenbegrenzung

​Verarbeitungsfehler

​Serverfehler

​Fehlerbehandlung

Fehlercodes

Format der Fehlerantwort

HTTP-Statuscodes

Fehler bei Transkription und Transkriptexport

Fehler bei Synchronisationsoptionen

Authentifizierungsfehler

Fehler bei der Dateiüberprüfung

Validierungsfehler

Ressourcenfehler

Ratenbegrenzung

Verarbeitungsfehler

Serverfehler

Fehlerbehandlung