> 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. # Błędy ## Błędy API ElevenLabs używa standardowych kodów stanu HTTP, aby wskazać powodzenie lub niepowodzenie żądania. Dodatkowo wszystkie żądania API zwracają obiekt JSON z właściwością `detail`, która zawiera informacje o błędzie. Zwykle kod stanu HTTP `200` oznacza udane żądanie. Kod `4xx` wskazuje problem z żądaniem, np. nieprawidłowy parametr lub brak wymaganego pola. Kod stanu HTTP `500` wskazuje problem z serwerami ElevenLabs, co powinno zdarzać się rzadko. ### Właściwości błędu | Właściwość | Opis | | ------------ | --------------------------------------------------------------------------------------------------------------------- | | `type` | Typ błędu, który wystąpił. Możliwe wartości znajdziesz w tabeli poniżej. | | `code` | Kod błędu. Jest bardziej szczegółowy niż typ i pozwala określić przyczynę błędu. | | `message` | Komunikat błędu. Zawiera więcej szczegółów o błędzie. | | `status` | Status błędu. To starsze pole, które nie jest już używane — zamiast niego używaj właściwości `code`. | | `request_id` | Identyfikator żądania, w którym wystąpił błąd. To unikalny identyfikator, który możesz wykorzystać do diagnozy błędu. | | `param` | Parametr, który spowodował błąd. W przypadku błędu walidacji wskazuje nieprawidłowy parametr. | ### Przykładowa odpowiedź z błędem Oto odpowiedź na żądanie API, w którym użyto nieprawidłowego identyfikatora modelu: ```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" } } ``` Na podstawie właściwości błędu widzimy, że jest to błąd walidacji, a kod to `invalid_parameters`. Komunikat zawiera więcej szczegółów, a `request_id` to unikalny identyfikator żądania, który możesz wykorzystać do diagnozy błędu. Właściwość `param` wskazuje parametr, który spowodował błąd. ### Obsługa błędów SDK SDK ElevenLabs udostępniają typowane klasy błędów, które dają dostęp do szczegółów błędu. ```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"); } } } } ``` Jeśli nie możesz rozwiązać problemu, napisz do działu wsparcia na [support@elevenlabs.io](mailto:support@elevenlabs.io). Podaj `request_id` z odpowiedzi błędu, pełny komunikat błędu oraz kroki pozwalające odtworzyć problem. #### Limity żądań i współbieżność Jeśli otrzymasz kod stanu HTTP 429, oznacza to, że w krótkim czasie wysłano zbyt wiele żądań i przekroczono limit żądań dla endpointu API albo przekroczono limit współbieżności dla tego endpointu. Odpowiedni `code` błędu to `rate_limit_exceeded` lub `concurrent_limit_exceeded`. W przypadku limitu żądań zaimplementuj w kodzie exponential backoff po otrzymaniu błędu 429. Oznacza to dodanie opóźnienia przed ponowną próbą wysłania żądania. W przypadku współbieżności poczekaj, aż bieżące żądania się zakończą, zanim wyślesz kolejne. Więcej informacji znajdziesz w sekcji [Współbieżność i priorytet](/docs/pl/overview/models#concurrency-and-priority). ### Typy błędów Błąd ma właściwość `type`, która wskazuje jego typ. Możliwe wartości znajdziesz w tabeli poniżej. | Typ | Opis | Kod stanu HTTP | | ---------------------- | -------------------------------------------------------------------------------- | -------------- | | `validation_error` | Żądanie zawiera nieprawidłowe wartości parametrów. | 400 | | `invalid_request` | Struktura żądania jest nieprawidłowa lub brakuje wymaganych pól. | 400 | | `authentication_error` | Uwierzytelnianie nie powiodło się — nieprawidłowy lub brakujący klucz/token API. | 401 | | `payment_required` | Użytkownik ma za mało środków lub wymagana jest płatność. | 402 | | `authorization_error` | Uwierzytelniony użytkownik nie ma wymaganych uprawnień do tej akcji. | 403 | | `not_found` | Nie znaleziono żądanego zasobu. | 404 | | `conflict` | Żądanie jest sprzeczne z bieżącym stanem zasobu. | 409 | | `rate_limit_error` | Zbyt wiele żądań — spróbuj ponownie później. | 429 | | `internal_error` | Wystąpił nieoczekiwany błąd serwera. | 500 | | `service_unavailable` | Usługa jest tymczasowo niedostępna, co powinno zdarzać się rzadko. | 503 | ### Kody błędów
Kod Typ Opis
`voice_not_found` `not_found` Podany identyfikator głosu nie istnieje. Sprawdź identyfikator głosu i spróbuj ponownie.
`sample_not_found` `not_found` Nie znaleziono podanej próbki głosu.
`voice_collection_not_found` `not_found` Podana kolekcja głosów nie istnieje.
`user_not_found` `not_found` Nie znaleziono podanego użytkownika.
`auth_account_not_found` `not_found` Nie znaleziono konta uwierzytelniania.
`workspace_not_found` `not_found` Podany obszar roboczy nie istnieje.
`project_not_found` `not_found` Nie znaleziono podanego projektu.
`history_item_not_found` `not_found` Podany element historii nie istnieje.
`collection_not_found` `not_found` Nie znaleziono podanej kolekcji.
`document_not_found` `not_found` Podany dokument nie istnieje.
`file_not_found` `not_found` Nie znaleziono podanego pliku.
`conversation_not_found` `not_found` Podana rozmowa nie istnieje.
`agent_not_found` `not_found` Nie znaleziono podanego agenta.
`dubbing_not_found` `not_found` Podany projekt dubbingowy nie istnieje.
`song_not_found` `not_found` Nie znaleziono podanego utworu.
`read_not_found` `not_found` Nie znaleziono podanego odczytu.
`pronunciation_dictionary_not_found` `not_found` Podany słownik wymowy nie istnieje.
`knowledge_base_not_found` `not_found` Nie znaleziono podanej bazy wiedzy.
`phone_number_not_found` `not_found` Podany numer telefonu nie istnieje.
`tool_not_found` `not_found` Nie znaleziono podanego narzędzia.
`snapshot_not_found` `not_found` Podany migawka nie istnieje.
`task_not_found` `not_found` Nie znaleziono podanego zadania.
`model_not_found` `not_found` Podany model nie istnieje.
`transcript_not_found` `not_found` Nie znaleziono podanej transkrypcji.
`keywords_list_not_found` `not_found` Nie znaleziono podanej listy słów kluczowych.
`category_not_found` `not_found` Nie znaleziono podanej kategorii.
`text_too_long` `validation_error` Podany tekst przekracza maksymalną dozwoloną długość.
`text_too_short` `validation_error` Podany tekst jest krótszy niż wymagana minimalna długość.
`invalid_text` `validation_error` Podany tekst zawiera nieprawidłowe znaki lub formatowanie.
`empty_text` `validation_error` Pole tekstowe nie może być puste.
`invalid_parameters` `validation_error` Co najmniej jeden parametr żądania jest nieprawidłowy. Sprawdź właściwość `param`, aby znaleźć nieprawidłowy parametr.
`missing_required_field` `validation_error` W żądaniu brakuje wymaganego pola. Sprawdź właściwość `param`, aby znaleźć brakujące pole.
`invalid_voice_settings` `validation_error` Ustawienia głosu zawierają nieprawidłowe wartości. Sprawdź właściwość `param`, aby znaleźć nieprawidłowe ustawienia głosu.
`invalid_voice_id` `validation_error` Format identyfikatora głosu jest nieprawidłowy.
`unsupported_model` `validation_error` Podany model nie jest obsługiwany w tej operacji.
`invalid_audio` `validation_error` Podane audio jest nieprawidłowe lub uszkodzone.
`invalid_audio_format` `validation_error` Podany format audio nie jest obsługiwany.
`invalid_output_format` `validation_error` Żądany format wyjściowy nie jest obsługiwany.
`audio_too_long` `validation_error` Audio przekracza maksymalną dozwoloną długość.
`audio_too_short` `validation_error` Audio jest krótsze niż wymagana minimalna długość.
`invalid_file_type` `validation_error` Typ pliku nie jest obsługiwany.
`invalid_page_size` `validation_error` Parametr rozmiaru strony jest poza dozwolonym zakresem.
`invalid_cursor` `validation_error` Kursor stronicowania jest nieprawidłowy lub wygasł.
`bad_request` `invalid_request` Serwer nie mógł zrozumieć żądania.
`malformed_json` `invalid_request` Treść żądania zawiera nieprawidłowy JSON.
`invalid_content_type` `invalid_request` Nagłówek Content-Type jest nieobecny lub nieprawidłowy.
`request_too_large` `invalid_request` Treść żądania przekracza maksymalny dozwolony rozmiar.
`invalid_api_key` `authentication_error` Podany klucz API jest nieprawidłowy.
`missing_api_key` `authentication_error` W żądaniu nie podano klucza API.
`invalid_authorization_header` `authentication_error` Format nagłówka Authorization jest nieprawidłowy.
`unauthorized` `authentication_error` Uwierzytelnianie jest wymagane, aby uzyskać dostęp do tego zasobu.
`sign_in_required` `authentication_error` Musisz się zalogować, aby wykonać tę akcję.
`forbidden` `authorization_error` Dostęp do tego zasobu jest zabroniony.
`insufficient_permissions` `authorization_error` Nie masz wymaganych uprawnień do tej akcji.
`workspace_access_denied` `authorization_error` Nie masz dostępu do tego obszaru roboczego.
`feature_not_available` `authorization_error` Ta funkcja nie jest dostępna w Twoim obecnym planie.
`subscription_required` `authorization_error` Do korzystania z tej funkcji wymagana jest płatna subskrypcja.
`voice_access_denied` `authorization_error` Nie masz dostępu do tego głosu.
`model_access_denied` `authorization_error` Nie masz dostępu do tego modelu.
`conflict` `conflict` Wystąpił konflikt.
`resource_already_exists` `conflict` Zasób z tym samym identyfikatorem już istnieje.
`voice_already_exists` `conflict` Głos o tej nazwie już istnieje.
`already_running` `conflict` Operacja jest już uruchomiona.
`already_processing` `conflict` Zasób jest już przetwarzany.
`concurrent_modification` `conflict` Zasób został zmieniony przez inne żądanie. Spróbuj ponownie z najnowszą wersją.
`slug_already_exists` `conflict` Zasób z tym slugiem już istnieje.
`rate_limit_exceeded` `rate_limit_error` Zbyt wiele żądań. Poczekaj przed ponowną próbą.
`concurrent_limit_exceeded` `rate_limit_error` Przekroczono maksymalną liczbę równoczesnych żądań. Wyższe poziomy subskrypcji mają wyższy limit współbieżności.
`system_busy` `rate_limit_error` System jest obecnie zajęty. Spróbuj ponownie później.
`insufficient_credits` `payment_required` Na Twoim koncie nie ma wystarczającej liczby środków na tę operację.
`internal_error` `internal_error` Wystąpił nieoczekiwany błąd. Skontaktuj się ze wsparciem, jeśli problem się powtarza.
`service_unavailable` `service_unavailable` Usługa jest tymczasowo niedostępna. Spróbuj ponownie później.
`maintenance` `service_unavailable` Usługa przechodzi zaplanowaną konserwację.