> ## 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. # Kody błędów > Pełna dokumentacja kodów błędów zwracanych przez API VoiceCheap # Kody błędów API VoiceCheap używa standardowych kodów statusu HTTP i zwraca ustrukturyzowane odpowiedzi o błędach, aby pomóc w ich płynnej obsłudze. ## Format odpowiedzi o błędzie Wszystkie odpowiedzi o błędach mają następującą strukturę: ```json theme={null} { "code": "ERROR_CODE", "message": "Human-readable description of the error" } ``` Niektóre błędy mogą zawierać dodatkowe pola. Błędy walidacji ładunku żądania zwracają jeden wpis na nieprawidłowe pole w `details`, a `field` jest pomijane, gdy komunikat o ograniczeniu nie wskazuje konkretnej właściwości: ```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"] } ] } ``` ## Kody stanu HTTP | Kod stanu | Znaczenie | | --------- | ---------------------------------------------------------------------- | | 200 | **OK** - Żądanie zakończone powodzeniem | | 400 | **Bad Request** - Nieprawidłowe parametry lub błąd walidacji | | 401 | **Unauthorized** - Nieprawidłowy lub brakujący klucz API | | 403 | **Forbidden** - Prawidłowy klucz API, ale niewystarczające uprawnienia | | 404 | **Not Found** - Zasób nie istnieje | | 409 | **Conflict** - Żądany wynik nie jest gotowy | | 413 | **Payload Too Large** - Przesłany plik przekracza limit | | 429 | **Too Many Requests** - Przekroczono limit żądań | | 500 | **Internal Server Error** - Wystąpił błąd po naszej stronie | | 502 | **Bad Gateway** - Silnik przetwarzania uległ awarii | ## Błędy transkrypcji i eksportu transkrypcji | Status | Kod | Znaczenie | | ------ | --------------------------- | ---------------------------------------------------------------------- | | 400 | `INVALID_MEDIA_STREAM` | Przesłane multimedia nie zawierają ścieżki audio | | 400 | `DURATION_TOO_LONG` | Samodzielne multimedia do transkrypcji są dłuższe niż dwie godziny | | 400 | `INVALID_BRAND_VOCABULARY` | Wpis w glosariuszu specyficzny dla żądania narusza limity | | 400 | `TARGET_LANGUAGE_REQUIRED` | Żądanie przetłumaczonej transkrypcji nie zawierało języka | | 404 | `TRANSCRIPT_NOT_FOUND` | Żądana oryginalna lub przetłumaczona transkrypcja jest nieobecna | | 409 | `TRANSCRIPT_NOT_READY` | Żądana transkrypcja jest w trakcie przetwarzania | | 502 | `TRANSCRIPTION_EMPTY` | Transkrypcja nie zawierała użytecznej mowy | | 502 | `TRANSCRIPTION_FAILED` | Silnik transkrypcji nie mógł ukończyć żądania | | 400 | `INVALID_MULTIPART_REQUEST` | Żądanie przesyłania wieloczęściowego jest błędne lub przekracza limity | ## Błędy opcji dubbingu | Status | Kod | Znaczenie | | ------ | ----------------------------------------------- | --------------------------------------------------------------------- | | 400 | `INVALID_SOURCE_SRT` | sourceSrt nie zawiera prawidłowych znaczników SRT | | 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt wymaga jawnego parametru originalLanguage | | 400 | `VOICE_ID_REQUIRED` | Tryb niestandardowe głosy wymaga identyfikatora głosu | | 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | voiceId został połączony z klonowanie głosu | | 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Ustawienia klonowania zostały połączone z trybem niestandardowe głosy | | 400 | `CONFLICTING_LIPSYNC_OPTIONS` | Nowoczesne i starsze pola synchronizacja ruchu ust są sprzeczne | | 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | Przeskoki czasowe wymagają dźwięk w tle | | 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | Przeskoki czasowe są sprzeczne z zachowaniem oryginalnego głosu | | 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Przeskok czasowy wykracza poza czas trwania multimediów | | 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Przeskok czasowy nakłada się na segment transkrypcji | | 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Wypalone napisy wymagają wejścia wideo | | 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | Synchronizacja ruchu ust wymaga wejścia wideo | | 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Przeskoki czasowe tłumaczenia wymagają wejścia wideo | | 403 | `CUSTOM_VOICE_ACCESS_DENIED` | Niestandardowe głosy nie należą do faktycznego właściciela | | 403 | `LIPSYNC_MODE_ACCESS_DENIED` | Tryb premium synchronizacja ruchu ust jest niedostępny w tym planie | ## Błędy uwierzytelniania **Status HTTP:** 401 Nagłówek `x-api-key` nie został dostarczony. **Rozwiązanie:** Dołącz swój klucz API w nagłówku `x-api-key`. ```json theme={null} { "code": "MISSING_API_KEY", "message": "API key is required. Please provide your API key in the x-api-key header." } ``` **Status HTTP:** 401 Klucz API nie używa oczekiwanego prefiksu `vc_`. **Rozwiązanie:** Sprawdź, czy skopiowano pełny klucz z aplikacji VoiceCheap. ```json theme={null} { "code": "INVALID_API_KEY_FORMAT", "message": "Invalid API key format. API keys must start with \"vc_\"." } ``` **Status HTTP:** 401 Podany klucz API jest nieprawidłowy lub wygasł. **Rozwiązanie:** Sprawdź, czy klucz API jest poprawny i zawarty w nagłówku `x-api-key`. ```json theme={null} { "code": "INVALID_API_KEY", "message": "The provided API key is invalid. Please check your API key and try again." } ``` **Status HTTP:** 403 Konto posiada ważny klucz, ale dostęp do API nie jest dla niego włączony. **Rozwiązanie:** Poproś o dostęp do API lub użyj konta, które ma już włączony dostęp do API. ```json theme={null} { "code": "API_ACCESS_REQUIRED", "message": "API access is required. Please request access to the API beta program." } ``` **Status HTTP:** 403 Dostęp do API wymaga aktywnej płatnej subskrypcji. **Rozwiązanie:** Przejdź na płatny plan w [voicecheap.ai](https://voicecheap.ai/pricing). ```json theme={null} { "code": "SUBSCRIPTION_REQUIRED", "message": "API access requires an active paid subscription. Please upgrade your plan." } ``` **Status HTTP:** 403 Twoje konto nie posiada wystarczającej liczby kredytów, aby przetworzyć to żądanie. **Rozwiązanie:** Dokup kredyty lub zmień swój plan subskrypcji na wyższy. ```json theme={null} { "code": "INSUFFICIENT_CREDITS", "message": "Insufficient credits to process this file. Please add more credits to your account." } ``` ## Błędy walidacji pliku **Status HTTP:** 400 Wraz z żądaniem nie przesłano żadnego pliku. **Rozwiązanie:** Dołącz plik w polu `file` swoich danych formularza multipart. ```json theme={null} { "code": "FILE_REQUIRED", "message": "A video or audio file is required. Please upload a file with your request." } ``` **Status HTTP:** 400 Przesłany typ pliku nie jest obsługiwany. **Rozwiązanie:** Prześlij plik w jednym z obsługiwanych formatów (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, ..." } ``` **Status HTTP:** 413 Przesłany plik przekracza limit dla uwierzytelnionej subskrypcji: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB lub Enterprise 60 GB. **Rozwiązanie:** Sprawdź limit swojego planu, a następnie skompresuj plik, podziel go na mniejsze segmenty lub zmień plan na wyższy. ```json theme={null} { "code": "FILE_TOO_LARGE", "message": "File size exceeds the 5GB limit for the beginner plan.", "maximumFileSizeBytes": 5368709120 } ``` **Status HTTP:** 400 Nie udało się wykryć czasu trwania przesłanego pliku. **Rozwiązanie:** Upewnij się, że plik jest poprawnym, nieuszkodzonym plikiem wideo lub audio. ```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." } ``` ## Błędy walidacji **Status HTTP:** 400 Określony język docelowy nie jest obsługiwany. **Rozwiązanie:** Użyj jednego z [obsługiwane języki](/docs/pl/introduction#supported-languages). ```json theme={null} { "code": "VALIDATION_ERROR", "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..." } ``` **Status HTTP:** 400 Parametr logiczny otrzymał nieprawidłową wartość. **Rozwiązanie:** Użyj `true` lub `false` (jako ciągów znaków w form-data). ```json theme={null} { "code": "INVALID_BOOLEAN_VALUE", "message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"." } ``` **Status HTTP:** 400 Nie można było przeanalizować parametru JSON. **Rozwiązanie:** Upewnij się, że ciąg JSON jest poprawnie sformatowany. ```json theme={null} { "code": "INVALID_JSON_FORMAT", "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON." } ``` **Status HTTP:** 400 Opcjonalne pole numeryczne form-data nie było prawidłową liczbą. Wyślij wartość liczbową z udokumentowanego zakresu. **Status HTTP:** 400 Zażądano synchronizacji ruchu ust dla mediów dłuższych niż obsługiwany czas trwania synchronizacji. **Rozwiązanie:** Pomiń `lipsyncPro` w tym żądaniu lub prześlij plik multimedialny mieszczący się w limicie synchronizacji ruchu ust. ```json theme={null} { "code": "LIPSYNC_VIDEO_TOO_LONG", "message": "LipSync supports up to 30 minutes. Your video is 45 minutes long." } ``` ## Błędy zasobów **Status HTTP:** 404 Określony projekt nie istnieje. **Rozwiązanie:** Sprawdź, czy identyfikator projektu jest poprawny. ```json theme={null} { "code": "PROJECT_NOT_FOUND", "message": "Project with ID 'abc123' not found." } ``` **Status HTTP:** 403 Nie masz uprawnień dostępu do tego zasobu. **Rozwiązanie:** Upewnij się, że używasz poprawnego klucza API dla tego projektu. ```json theme={null} { "code": "FORBIDDEN", "message": "You do not have permission to access this project." } ``` ## Ograniczenie częstotliwości zapytań **Status HTTP:** 429 Przekroczono limit częstotliwości zapytań dla tego punktu końcowego. **Rozwiązanie:** Odczekaj przed wysłaniem kolejnych żądań. Użyj wykładniczego wycofywania (exponential backoff). | Punkt końcowy | Limit częstotliwości | | ------------------------------- | -------------------- | | `POST /v1/translate` | 10 żądań na minutę | | `POST /v1/projects` | 10 żądań na minutę | | `GET /v1/translate/{id}/status` | 30 żądań na minutę | | `GET /v1/projects/{id}` | 20 żądań na minutę | | `DELETE /v1/translate/{id}` | 10 żądań na minutę | ```json theme={null} { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please wait before trying again." } ``` **Status HTTP:** 429 Masz już uruchomioną maksymalną liczbę tłumaczeń równolegle. **Rozwiązanie:** Poczekaj, aż jedno z trwających tłumaczeń się zakończy, a następnie ponów żądanie. ```json theme={null} { "code": "CONCURRENT_TRANSLATION_LIMIT_REACHED", "message": "Concurrent translation limit reached. You can run up to 10 translations at the same time." } ``` ## Błędy przetwarzania Te błędy mogą zostać zwrócone w polu `error` podczas sprawdzania statusu tłumaczenia: Nie można było dokonać transkrypcji dźwięku. **Możliwe przyczyny:** * Zbyt niska jakość dźwięku * W dźwięku nie wykryto mowy * Nieobsługiwane kodowanie dźwięku ```json theme={null} { "code": "TRANSCRIPTION_FAILED", "message": "Could not transcribe the audio. Please ensure the audio quality is sufficient." } ``` Nie można było przetłumaczyć transkrypcji. **Możliwe przyczyny:** * Nieobsługiwana para językowa * Nie udało się przetworzyć zawartości ```json theme={null} { "code": "TRANSLATION_FAILED", "message": "Failed to translate the content. Please try again." } ``` Synteza głosu nie powiodła się podczas dubbingu. **Możliwe przyczyny:** * Klonowanie głosu nie powiodło się * Błąd generowania dźwięku ```json theme={null} { "code": "VOICE_SYNTHESIS_FAILED", "message": "Failed to generate the dubbed audio. Please try again." } ``` Przetwarzanie synchronizacji ruchu ust nie powiodło się. **Możliwe przyczyny:** * Błąd dostawcy synchronizacji ruchu ust * Nieprawidłowe lub nieobsługiwane media * Żądanie zostało odrzucone lub anulowane ```json theme={null} { "code": "LIPSYNC_FAILED", "message": "Lip sync failed." } ``` ## Błędy serwera **Kod stanu HTTP:** 500 Na naszych serwerach wystąpił nieoczekiwany błąd. **Rozwiązanie:** Ponów żądanie. Jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną. ```json theme={null} { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ``` ## Obsługa błędów ```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}") ```