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ę:

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

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

MISSING_API_KEY

Status HTTP: 401Nagłówek x-api-key nie został dostarczony.Rozwiązanie: Dołącz swój klucz API w nagłówku x-api-key.

{
  "code": "MISSING_API_KEY",
  "message": "API key is required. Please provide your API key in the x-api-key header."
}

INVALID_API_KEY_FORMAT

Status HTTP: 401Klucz API nie używa oczekiwanego prefiksu vc_.Rozwiązanie: Sprawdź, czy skopiowano pełny klucz z aplikacji VoiceCheap.

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

INVALID_API_KEY

Status HTTP: 401Podany klucz API jest nieprawidłowy.Rozwiązanie: Sprawdź, czy klucz API jest poprawny i zawarty w nagłówku x-api-key.

{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key. Please check your API key and try again."
}

SUBSCRIPTION_REQUIRED

Status HTTP: 403Dostęp do API i MCP wymaga planu Starter lub wyższego.Rozwiązanie: Przejdź na plan Starter lub wyższy w voicecheap.ai.

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

INSUFFICIENT_CREDITS

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

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

FILE_REQUIRED

Status HTTP: 400Wraz z żądaniem nie przesłano żadnego pliku.Rozwiązanie: Dołącz plik w polu file swoich danych formularza multipart.

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

INVALID_FILE_TYPE

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

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

FILE_TOO_LARGE

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

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

DURATION_DETECTION_FAILED

Status HTTP: 400Nie udało się wykryć czasu trwania przesłanego pliku.Rozwiązanie: Upewnij się, że plik jest poprawnym, nieuszkodzonym plikiem wideo lub audio.

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

INVALID_TARGET_LANGUAGE

Status HTTP: 400Określony język docelowy nie jest obsługiwany.Rozwiązanie: Użyj jednego z obsługiwane języki.

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

INVALID_BOOLEAN_VALUE

Status HTTP: 400Parametr logiczny otrzymał nieprawidłową wartość.Rozwiązanie: Użyj true lub false (jako ciągów znaków w form-data).

{
  "code": "INVALID_BOOLEAN_VALUE",
  "message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
}

INVALID_JSON_FORMAT

Status HTTP: 400Nie można było przeanalizować parametru JSON.Rozwiązanie: Upewnij się, że ciąg JSON jest poprawnie sformatowany.

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

INVALID_NUMBER_VALUE

Status HTTP: 400Opcjonalne pole numeryczne form-data nie było prawidłową liczbą. Wyślij wartość liczbową z udokumentowanego zakresu.

LIPSYNC_VIDEO_TOO_LONG

Status HTTP: 400Zażą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.

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

Błędy zasobów

PROJECT_NOT_FOUND

Status HTTP: 404Określony projekt nie istnieje.Rozwiązanie: Sprawdź, czy identyfikator projektu jest poprawny.

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

FORBIDDEN

Status HTTP: 403Nie masz uprawnień dostępu do tego zasobu.Rozwiązanie: Upewnij się, że używasz poprawnego klucza API dla tego projektu.

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

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

{
  "code": "TRANSCRIPTION_FAILED",
  "message": "The transcription could not be completed. Please try again."
}

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

{
  "code": "TRANSLATION_FAILED",
  "message": "The translation could not be completed. Please try again."
}

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

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync could not be completed. Please try again."
}

Błędy serwera

INTERNAL_ERROR

Kod stanu HTTP: 500Na naszych serwerach wystąpił nieoczekiwany błąd.Rozwiązanie: Ponów żądanie. Jeśli problem będzie się powtarzał, skontaktuj się z pomocą techniczną.

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

Obsługa błędów

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

Przegląd

Wykrywanie

Konto

Wykorzystanie i aktywność

Ustawienia i powiadomienia

Zespół

Projekty

Tłumaczenie i dubbing

Transkrypcje i edycja

Zamiana tekstu na mowę

Głosy do syntezy mowy

Głosy dubbingowe

Transkrypcja

Napisy

Obrazy

Miniatury

Foldery

Glosariusz

Webhooki

Publikowanie

Stan żądania

OAuth i protokół MCP

Kody błędów

Kody błędów

Format odpowiedzi o błędzie

Kody stanu HTTP

Błędy transkrypcji i eksportu transkrypcji

Błędy opcji dubbingu

Asynchroniczne błędy dopasowania SRT

Błędy uwierzytelniania

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

Błędy walidacji pliku

Błędy walidacji

Błędy zasobów

Błędy uprawnień i użycia

Błędy przetwarzania

Błędy serwera

Obsługa błędów

​Kody błędów

​Format odpowiedzi o błędzie

​Kody stanu HTTP

​Błędy transkrypcji i eksportu transkrypcji

​Błędy opcji dubbingu

​Asynchroniczne błędy dopasowania SRT

​Błędy uwierzytelniania

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

​Błędy walidacji pliku

​Błędy walidacji

​Błędy zasobów

​Błędy uprawnień i użycia

​Błędy przetwarzania

​Błędy serwera

​Obsługa błędów

Kody błędów

Format odpowiedzi o błędzie

Kody stanu HTTP

Błędy transkrypcji i eksportu transkrypcji

Błędy opcji dubbingu

Asynchroniczne błędy dopasowania SRT

Błędy uwierzytelniania

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

Błędy walidacji pliku

Błędy walidacji

Błędy zasobów

Błędy uprawnień i użycia

Błędy przetwarzania

Błędy serwera

Obsługa błędów