> ## 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** - Projekt nie jest w stanie, który pozwala na to żądanie |
| 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** - Nie udało się ukończyć transkrypcji |

## 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` | Nie udało się ukończyć transkrypcji |
| 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 | `INVALID_TRANSLATED_SRT` | translatedSrt nie zawiera prawidłowych cue SRT |
| 400 | `TRANSLATED_SRT_CUE_COUNT_MISMATCH` | Liczba cue w translatedSrt i sourceSrt jest różna |
| 409 | `DUB_ONLY_REQUIRES_TRANSCRIPTION` | Projekt nie ma ukończonej transkrypcji do dubbingu |
| 409 | `TRANSLATION_ALREADY_IN_PROGRESS` | Dubbing dla tego języka jest już w toku |
| 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` | Wybrany głos nie pochodzi z katalogu ani nie jest głosem niestandardowym zapisanym przez uwierzytelnione konto. |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | Tryb premium synchronizacja ruchu ust jest niedostępny w tym planie |

## Asynchroniczne błędy dopasowania SRT

Te błędy występują po przyjęciu żądania tłumaczenia lub dubbingu. Endpoint statusu odpowiada HTTP 200 ze `status: "failed"`; jego `error` i webhook `project.translation.failed` zawierają tylko `code` oraz `message`. Zapisane błędy używają stałych komunikatów VoiceCheap; nie zawierają numerów cue ani indeksów segmentów. Synchroniczne błędy żądania, w tym `TRANSLATED_SRT_CUE_COUNT_MISMATCH`, nadal mają HTTP 400 w powyższej tabeli.

| Wynik | Code | Znaczenie |
| - | - | - |
| `GET` 200 / webhook | `TRANSLATED_SRT_UNMATCHED_CUES` | Przetłumaczony cue nie pasuje do żadnego segmentu transkrypcji (zgłaszane w statusie i webhookach) |
| `GET` 200 / webhook | `TRANSLATED_SRT_MISSING_SEGMENTS` | Segment transkrypcji nie ma przetłumaczonego cue (zgłaszane w statusie i webhookach) |

## Błędy uwierzytelniania

> [accordion] MISSING\_API\_KEY
>
> **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."
> }
> ```

> [accordion] INVALID\_API\_KEY\_FORMAT
>
> **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_\"."
> }
> ```

> [accordion] INVALID\_API\_KEY
>
> **Status HTTP:** 401
>
> Podany klucz API jest nieprawidłowy.
>
> **Rozwiązanie:** Sprawdź, czy klucz API jest poprawny i zawarty w nagłówku `x-api-key`.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY",
>   "message": "Invalid API key. Please check your API key and try again."
> }
> ```

> [accordion] SUBSCRIPTION\_REQUIRED
>
> **Status HTTP:** 403
>
> Dostęp do API i MCP wymaga planu Starter lub wyższego.
>
> **Rozwiązanie:** Przejdź na plan Starter lub wyższy w [voicecheap.ai](https://voicecheap.ai/pricing).
>
> ```json theme={null}
> {
>   "code": "SUBSCRIPTION_REQUIRED",
>   "message": "A Starter plan or higher is required to use the API and MCP. Please upgrade your account at voicecheap.ai/pricing."
> }
> ```

> [accordion] INSUFFICIENT\_CREDITS
>
> **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."
> }
> ```

## Pozostałe błędy uwierzytelniania i zespołu

| HTTP | Kod | Opis |
| - | - | - |
| 401 | `USER_NOT_FOUND` | Nie znaleziono konta powiązanego z tym kluczem |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | Posiadacz klucza należy do kilku zespołów; skontaktuj się z pomocą techniczną |
| 403 | `TEAM_OWNER_NOT_FOUND` | Nie znaleziono konta właściciela powiązanego zespołu |

## Błędy walidacji pliku

> [accordion] FILE\_REQUIRED
>
> **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."
> }
> ```

> [accordion] INVALID\_FILE\_TYPE
>
> **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, ..."
> }
> ```

> [accordion] FILE\_TOO\_LARGE
>
> **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
> }
> ```

> [accordion] DURATION\_DETECTION\_FAILED
>
> **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

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **Status HTTP:** 400
>
> Określony język docelowy nie jest obsługiwany.
>
> **Rozwiązanie:** Użyj jednego z [obsługiwane języki](https://api-docs.voicecheap.ai/docs/pl/introduction.md#supported-languages).
>
> ```json theme={null}
> {
>   "code": "VALIDATION_ERROR",
>   "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
> }
> ```

> [accordion] INVALID\_BOOLEAN\_VALUE
>
> **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\"."
> }
> ```

> [accordion] INVALID\_JSON\_FORMAT
>
> **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."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **Status HTTP:** 400
>
> Opcjonalne pole numeryczne form-data nie było prawidłową liczbą. Wyślij wartość liczbową z udokumentowanego zakresu.

> [accordion] LIPSYNC\_VIDEO\_TOO\_LONG
>
> **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 180 minutes. Your video is 181 minutes long."
> }
> ```

## Błędy zasobów

> [accordion] PROJECT\_NOT\_FOUND
>
> **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."
> }
> ```

> [accordion] FORBIDDEN
>
> **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."
> }
> ```

## Błędy uprawnień i użycia

| Status | Kod | Działanie |
| - | - | - |
| 401 | `API_KEY_EXPIRED`, `INVALID_MCP_TOKEN` | Użyj ważnego, niewygasłego klucza lub ponownie połącz asystenta. |
| 403 | `INSUFFICIENT_SCOPE` | Przyznaj wymagane uprawnienie lub wybierz inne poświadczenie. |
| 403 | `SUBSCRIPTION_REQUIRED` | Korzystaj z planu Starter lub wyższego. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Poczekaj na miesięczny reset lub zmień plan. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED` | Odczekaj przed ponowną próbą i stopniowo zwiększaj opóźnienie. |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Poczekaj na zakończenie trwającego generowania. |
| 400 | `VALIDATION_ERROR` | Popraw argumenty zgodnie ze schematem danych wejściowych w katalogu. |
| 404 | `UNKNOWN_ACTION` | Użyj obsługiwanej nazwy akcji uzyskanej podczas wykrywania. |

Wspólną pulę konta opisano na stronie [użycia i limitów](https://api-docs.voicecheap.ai/docs/pl/api-reference/limits.md). Błędy nie zużywają miesięcznych wywołań. `action_request_get`, `usage_get`, `projects_status` i `GET /v1/translate/{projectId}/status` nie zużywają miesięcznej puli.

## Błędy przetwarzania

Te błędy mogą zostać zwrócone w polu `error` podczas sprawdzania statusu tłumaczenia:

> [accordion] TRANSCRIPTION\_FAILED
>
> 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": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] TRANSLATION\_FAILED
>
> 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": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] LIPSYNC\_FAILED
>
> Przetwarzanie synchronizacji ruchu ust nie powiodło się.
>
> **Możliwe przyczyny:**
>
> * Przejściowy problem podczas synchronizacji ruchu ust
> * Nieprawidłowe lub nieobsługiwane media
> * Żądanie zostało odrzucone lub anulowane
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## Błędy serwera

> [accordion] INTERNAL\_ERROR
>
> **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}")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.