> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Fehler ## API-Fehler ElevenLabs verwendet standardmäßige HTTP-Statuscodes, um den Erfolg oder Fehler einer Anfrage anzuzeigen. Zusätzlich geben alle API-Anfragen ein JSON-Objekt mit einer `detail`-Eigenschaft zurück, die Informationen zum Fehler enthält. Im Allgemeinen weist ein HTTP-Statuscode `200` auf eine erfolgreiche Anfrage hin. Ein `4xx`-Code weist auf ein Problem mit der Anfrage hin, etwa einen ungültigen Parameter oder ein fehlendes Pflichtfeld. Ein HTTP-Statuscode `500` weist auf ein Problem mit den Servern von ElevenLabs hin, was selten vorkommen sollte. ### Fehlereigenschaften | Eigenschaft | Beschreibung | | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `type` | Der aufgetretene Fehlertyp. Mögliche Werte finden Sie in der folgenden Tabelle. | | `code` | Der Fehlercode. Er ist spezifischer als der Typ und kann zur Bestimmung der Fehlerursache verwendet werden. | | `message` | Die Fehlermeldung. Sie enthält weitere Details zum Fehler. | | `status` | Der Fehlerstatus. Dies ist ein nicht mehr verwendetes Legacy-Feld; nutzen Sie stattdessen die Eigenschaft `code`. | | `request_id` | Die Anfragen-ID des Fehlers. Dies ist eine eindeutige Kennung für die Anfrage, die zur Fehlerbehebung verwendet werden kann. | | `param` | Der Parameter, der den Fehler verursacht hat. Bei einem Validierungsfehler zeigt er den ungültigen Parameter an. | ### Beispiel für eine Fehlerantwort Hier ist die Antwort für eine API-Anfrage mit einer falschen Modell-ID: ```json { "detail": { "type": "validation_error", "code": "invalid_parameters", "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.", "status": "invalid_parameters", "request_id": "3c807fc4c3a1705f9638ecc764a91c01", "param": "keyterms" } } ``` Anhand der Fehlereigenschaften sehen wir, dass es sich um einen Validierungsfehler handelt und der Code `invalid_parameters` lautet. Die Meldung enthält weitere Details zum Fehler und die `request_id` ist eine eindeutige Kennung für die Anfrage, die zur Fehlerbehebung verwendet werden kann. Die Eigenschaft `param` gibt den Parameter an, der den Fehler verursacht hat. ### Fehlerbehandlung im SDK Die ElevenLabs SDKs bieten typisierte Fehlerklassen, die Ihnen Zugriff auf die Fehlerdetails geben. ```python from elevenlabs import ElevenLabs from elevenlabs.core import ApiError elevenlabs = ElevenLabs() try: audio = elevenlabs.text_to_speech.convert( voice_id="invalid-voice-id", model_id="eleven_v4", text="Hello, world!", ) except ApiError as e: print(f"Status code: {e.status_code}") # Access the error body if e.body and "detail" in e.body: detail = e.body["detail"] print(f"Error type: {detail.get('type')}") print(f"Error code: {detail.get('code')}") print(f"Message: {detail.get('message')}") print(f"Request ID: {detail.get('request_id')}") # Handle specific error types if detail.get("type") == "rate_limit_error": print("Rate limited - implement exponential backoff") elif detail.get("type") == "authentication_error": print("Check your API key") ``` ```typescript import { ElevenLabsClient, ElevenLabsError } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); try { const audio = await elevenlabs.textToSpeech.convert("invalid-voice-id", { text: "Hello, world!", modelId: "eleven_v4", }); } catch (error) { if (error instanceof ElevenLabsError) { console.log(`Status code: ${error.statusCode}`); // Access the error body const detail = (error.body as any)?.detail; if (detail) { console.log(`Error type: ${detail.type}`); console.log(`Error code: ${detail.code}`); console.log(`Message: ${detail.message}`); console.log(`Request ID: ${detail.request_id}`); // Handle specific error types if (detail.type === "rate_limit_error") { console.log("Rate limited - implement exponential backoff"); } else if (detail.type === "authentication_error") { console.log("Check your API key"); } } } } ``` Wenn Sie den Fehler nicht beheben können, senden Sie dem Support unter [support@elevenlabs.io](mailto:support@elevenlabs.io) eine E-Mail mit der `request_id` aus der Fehlerantwort, der vollständigen Fehlermeldung und Schritten zur Reproduktion des Problems. #### Ratenbegrenzung und Parallelität Wenn Sie einen HTTP-Statuscode 429 erhalten, haben Sie entweder in kurzer Zeit zu viele Anfragen gestellt und das Ratenlimit für den API-Endpunkt überschritten oder das Parallelitätslimit für den API-Endpunkt überschritten. Der Fehler-`code` lautet entsprechend `rate_limit_exceeded` oder `concurrent_limit_exceeded`. Bei einer Ratenbegrenzung sollten Sie in Ihrem Code exponentielles Backoff implementieren, wenn ein 429-Fehler auftritt. Das bedeutet, vor dem erneuten Senden der Anfrage eine Verzögerung hinzuzufügen. Bei Parallelität sollten Sie warten, bis die aktuellen Anfragen abgeschlossen sind, bevor Sie neue stellen. Weitere Informationen finden Sie im Abschnitt [Parallelität und Priorität](/docs/de/overview/models#concurrency-and-priority). ### Fehlertypen Ein Fehler enthält eine `type`-Eigenschaft, die den aufgetretenen Fehlertyp angibt. Mögliche Werte finden Sie in der folgenden Tabelle. | Typ | Beschreibung | HTTP-Statuscode | | ---------------------- | ------------------------------------------------------------------------------------------- | --------------- | | `validation_error` | Die Anfrage enthält ungültige Parameterwerte. | 400 | | `invalid_request` | Die Anfragestruktur ist fehlerhaft oder Pflichtfelder fehlen. | 400 | | `authentication_error` | Die Authentifizierung ist fehlgeschlagen – API-Schlüssel/Token ungültig oder fehlt. | 401 | | `payment_required` | Der Benutzer verfügt über unzureichende Credits oder eine Zahlung ist erforderlich. | 402 | | `authorization_error` | Der authentifizierte Benutzer hat nicht die erforderlichen Berechtigungen für diese Aktion. | 403 | | `not_found` | Die angeforderte Ressource wurde nicht gefunden. | 404 | | `conflict` | Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource. | 409 | | `rate_limit_error` | Zu viele Anfragen – versuchen Sie es später erneut. | 429 | | `internal_error` | Ein unerwarteter Serverfehler ist aufgetreten. | 500 | | `service_unavailable` | Der Dienst ist vorübergehend nicht verfügbar. Dies sollte selten vorkommen. | 503 | ### Fehlercodes
Code Typ Beschreibung
`voice_not_found` `not_found` Die angegebene Stimmen-ID existiert nicht. Prüfen Sie die Stimmen-ID und versuchen Sie es erneut.
`sample_not_found` `not_found` Das angegebene Stimmen-Sample wurde nicht gefunden.
`voice_collection_not_found` `not_found` Die angegebene Stimmensammlung existiert nicht.
`user_not_found` `not_found` Der angegebene Benutzer wurde nicht gefunden.
`auth_account_not_found` `not_found` Das Authentifizierungskonto wurde nicht gefunden.
`workspace_not_found` `not_found` Der angegebene Workspace existiert nicht.
`project_not_found` `not_found` Das angegebene Projekt wurde nicht gefunden.
`history_item_not_found` `not_found` Das angegebene Verlaufselement existiert nicht.
`collection_not_found` `not_found` Die angegebene Sammlung wurde nicht gefunden.
`document_not_found` `not_found` Das angegebene Dokument existiert nicht.
`file_not_found` `not_found` Die angegebene Datei wurde nicht gefunden.
`conversation_not_found` `not_found` Die angegebene Unterhaltung existiert nicht.
`agent_not_found` `not_found` Der angegebene Agent wurde nicht gefunden.
`dubbing_not_found` `not_found` Das angegebene Synchronisationsprojekt existiert nicht.
`song_not_found` `not_found` Der angegebene Song wurde nicht gefunden.
`read_not_found` `not_found` Der angegebene Read wurde nicht gefunden.
`pronunciation_dictionary_not_found` `not_found` Das angegebene Aussprachewörterbuch existiert nicht.
`knowledge_base_not_found` `not_found` Die angegebene Wissensdatenbank wurde nicht gefunden.
`phone_number_not_found` `not_found` Die angegebene Telefonnummer existiert nicht.
`tool_not_found` `not_found` Das angegebene Tool wurde nicht gefunden.
`snapshot_not_found` `not_found` Der angegebene Snapshot existiert nicht.
`task_not_found` `not_found` Die angegebene Aufgabe wurde nicht gefunden.
`model_not_found` `not_found` Das angegebene Modell existiert nicht.
`transcript_not_found` `not_found` Das angegebene Transkript wurde nicht gefunden.
`keywords_list_not_found` `not_found` Die angegebene Schlüsselwortliste wurde nicht gefunden.
`category_not_found` `not_found` Die angegebene Kategorie wurde nicht gefunden.
`text_too_long` `validation_error` Der bereitgestellte Text überschreitet die maximal zulässige Länge.
`text_too_short` `validation_error` Der bereitgestellte Text ist kürzer als die erforderliche Mindestlänge.
`invalid_text` `validation_error` Der bereitgestellte Text enthält ungültige Zeichen oder Formatierungen.
`empty_text` `validation_error` Das Textfeld darf nicht leer sein.
`invalid_parameters` `validation_error` Ein oder mehrere Anfrageparameter sind ungültig. Prüfen Sie die Eigenschaft `param` auf den ungültigen Parameter.
`missing_required_field` `validation_error` Ein Pflichtfeld fehlt in der Anfrage. Prüfen Sie die Eigenschaft `param` auf das fehlende Feld.
`invalid_voice_settings` `validation_error` Die Stimmeneinstellungen enthalten ungültige Werte. Prüfen Sie die Eigenschaft `param` auf die ungültigen Stimmeneinstellungen.
`invalid_voice_id` `validation_error` Das Format der Stimmen-ID ist ungültig.
`unsupported_model` `validation_error` Das angegebene Modell wird für diesen Vorgang nicht unterstützt.
`invalid_audio` `validation_error` Das bereitgestellte Audio ist ungültig oder beschädigt.
`invalid_audio_format` `validation_error` Das angegebene Audioformat wird nicht unterstützt.
`invalid_output_format` `validation_error` Das angeforderte Ausgabeformat wird nicht unterstützt.
`audio_too_long` `validation_error` Das Audio überschreitet die maximal zulässige Dauer.
`audio_too_short` `validation_error` Das Audio ist kürzer als die erforderliche Mindestdauer.
`invalid_file_type` `validation_error` Der Dateityp wird nicht unterstützt.
`invalid_page_size` `validation_error` Der Parameter für die Seitengröße liegt außerhalb des zulässigen Bereichs.
`invalid_cursor` `validation_error` Der Paginierungs-Cursor ist ungültig oder abgelaufen.
`bad_request` `invalid_request` Der Server konnte die Anfrage nicht verstehen.
`malformed_json` `invalid_request` Der Anfrage-Body enthält ungültiges JSON.
`invalid_content_type` `invalid_request` Der Content-Type-Header fehlt oder ist ungültig.
`request_too_large` `invalid_request` Der Anfrage-Body überschreitet die maximal zulässige Größe.
`invalid_api_key` `authentication_error` Der bereitgestellte API-Schlüssel ist ungültig.
`missing_api_key` `authentication_error` In der Anfrage wurde kein API-Schlüssel bereitgestellt.
`invalid_authorization_header` `authentication_error` Das Format des Authorization-Headers ist ungültig.
`unauthorized` `authentication_error` Für den Zugriff auf diese Ressource ist eine Authentifizierung erforderlich.
`sign_in_required` `authentication_error` Sie müssen angemeldet sein, um diese Aktion auszuführen.
`forbidden` `authorization_error` Der Zugriff auf diese Ressource ist untersagt.
`insufficient_permissions` `authorization_error` Sie haben nicht die erforderlichen Berechtigungen für diese Aktion.
`workspace_access_denied` `authorization_error` Sie haben keinen Zugriff auf diesen Workspace.
`feature_not_available` `authorization_error` Diese Funktion ist in Ihrem aktuellen Tarif nicht verfügbar.
`subscription_required` `authorization_error` Für den Zugriff auf diese Funktion ist ein kostenpflichtiges Abonnement erforderlich.
`voice_access_denied` `authorization_error` Sie haben keinen Zugriff auf diese Stimme.
`model_access_denied` `authorization_error` Sie haben keinen Zugriff auf dieses Modell.
`conflict` `conflict` Ein Konflikt ist aufgetreten.
`resource_already_exists` `conflict` Eine Ressource mit derselben Kennung existiert bereits.
`voice_already_exists` `conflict` Eine Stimme mit diesem Namen existiert bereits.
`already_running` `conflict` Der Vorgang wird bereits ausgeführt.
`already_processing` `conflict` Die Ressource wird bereits verarbeitet.
`concurrent_modification` `conflict` Die Ressource wurde durch eine andere Anfrage geändert. Wiederholen Sie den Vorgang mit der neuesten Version.
`slug_already_exists` `conflict` Eine Ressource mit diesem Slug existiert bereits.
`rate_limit_exceeded` `rate_limit_error` Zu viele Anfragen. Warten Sie, bevor Sie es erneut versuchen.
`concurrent_limit_exceeded` `rate_limit_error` Die maximale Anzahl paralleler Anfragen wurde überschritten. Höhere Abonnementstufen haben ein höheres Parallelitätslimit.
`system_busy` `rate_limit_error` Das System ist derzeit ausgelastet. Versuchen Sie es später erneut.
`insufficient_credits` `payment_required` Ihr Konto hat nicht genügend Credits für diesen Vorgang.
`internal_error` `internal_error` Ein unerwarteter Fehler ist aufgetreten. Wenden Sie sich an den Support, wenn das Problem weiterhin besteht.
`service_unavailable` `service_unavailable` Der Dienst ist vorübergehend nicht verfügbar. Versuchen Sie es später erneut.
`maintenance` `service_unavailable` Der Dienst wird planmäßig gewartet.