Códigos de Erro

A API VoiceCheap usa códigos de status HTTP padrão e retorna respostas de erro estruturadas para ajudá-lo a lidar com erros de forma elegante.

Formato de Resposta de Erro

Todas as respostas de erro seguem esta estrutura:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}

Alguns erros podem incluir campos adicionais. Falhas na validação do payload da solicitação retornam uma entrada por campo inválido em details, e field é omitido quando a mensagem de restrição não nomeia uma propriedade específica:

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": [
    {
      "field": "outputFormat",
      "messages": ["outputFormat must be one of the following values: json, srt, vtt"]
    }
  ]
}

Códigos de Status HTTP

Código de Status	Significado
200	OK - Solicitação bem-sucedida
400	Bad Request - Parâmetros inválidos ou erro de validação
401	Unauthorized - Chave de API inválida ou ausente
403	Forbidden - Chave de API válida, mas permissões insuficientes
404	Not Found - O recurso não existe
409	Conflict - O resultado solicitado não está pronto
413	Payload Too Large - O arquivo enviado excede seu limite
429	Too Many Requests - Limite de taxa excedido
500	Internal Server Error - Algo deu errado do nosso lado
502	Bad Gateway - Um mecanismo de processamento falhou

Erros de transcrição e exportação de transcrição

Status	Código	Significado
400	`INVALID_MEDIA_STREAM`	A mídia enviada não contém um fluxo de áudio
400	`DURATION_TOO_LONG`	A mídia de transcrição independente tem mais de duas horas
400	`INVALID_BRAND_VOCABULARY`	Uma entrada de glossário específica da solicitação viola os limites
400	`TARGET_LANGUAGE_REQUIRED`	Uma solicitação de transcrição traduzida omitiu seu idioma
404	`TRANSCRIPT_NOT_FOUND`	A transcrição original ou traduzida solicitada está ausente
409	`TRANSCRIPT_NOT_READY`	A transcrição solicitada ainda está sendo processada
502	`TRANSCRIPTION_EMPTY`	A transcrição não continha fala utilizável
502	`TRANSCRIPTION_FAILED`	O mecanismo de transcrição não pôde concluir a solicitação
400	`INVALID_MULTIPART_REQUEST`	A solicitação de upload multipart está malformada ou excede os limites

Erros de opção de dublagem

Status	Código	Significado
400	`INVALID_SOURCE_SRT`	sourceSrt não contém indicações SRT válidas
400	`SOURCE_LANGUAGE_REQUIRED_FOR_SRT`	sourceSrt requer um originalLanguage explícito
400	`VOICE_ID_REQUIRED`	O modo de vozes personalizadas requer um ID de voz
400	`VOICE_ID_NOT_ALLOWED_WITH_CLONING`	voiceId foi combinado com clonagem de voz
400	`VOICE_CLONING_SETTINGS_NOT_ALLOWED`	As configurações de clone foram combinadas com o modo de vozes personalizadas
400	`CONFLICTING_LIPSYNC_OPTIONS`	Os campos de sincronização labial modernos e legados discordam
400	`TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND`	Pulos de tempo requerem áudio de fundo
400	`TRANSLATION_TIME_SKIP_CONFLICT`	Pulos de tempo conflitam com a retenção da voz original
400	`TRANSLATION_TIME_SKIP_OUT_OF_RANGE`	Um pulo de tempo se estende além da duração da mídia
400	`INVALID_TRANSLATION_TIME_SKIPS`	Um pulo de tempo sobrepõe um segmento de transcrição
400	`SUBTITLES_NOT_AVAILABLE_FOR_AUDIO`	Legendas embutidas requerem entrada de vídeo
400	`LIPSYNC_NOT_AVAILABLE_FOR_AUDIO`	Sincronização labial requer entrada de vídeo
400	`TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO`	Pulos de tempo de tradução requerem entrada de vídeo
403	`CUSTOM_VOICE_ACCESS_DENIED`	A voz personalizada não pertence ao proprietário efetivo
403	`LIPSYNC_MODE_ACCESS_DENIED`	O modo de sincronização labial premium não está disponível no plano

Erros de Autenticação

MISSING_API_KEY

Status HTTP: 401O cabeçalho x-api-key não foi fornecido.Solução: Inclua sua chave de API no cabeçalho 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: 401A chave de API não utiliza o prefixo vc_ esperado.Solução: Verifique se você copiou a chave completa do aplicativo VoiceCheap.

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

INVALID_API_KEY

Status HTTP: 401A chave de API fornecida é inválida ou expirou.Solução: Verifique se sua chave de API está correta e incluída no cabeçalho x-api-key.

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid. Please check your API key and try again."
}

API_ACCESS_REQUIRED

Status HTTP: 403A conta possui uma chave válida, mas o acesso à API não está habilitado para essa conta.Solução: Solicite acesso à API ou use uma conta que já tenha o acesso à API habilitado.

{
  "code": "API_ACCESS_REQUIRED",
  "message": "API access is required. Please request access to the API beta program."
}

SUBSCRIPTION_REQUIRED

Status HTTP: 403O acesso à API requer uma assinatura paga ativa.Solução: Faça upgrade para um plano pago em voicecheap.ai.

{
  "code": "SUBSCRIPTION_REQUIRED",
  "message": "API access requires an active paid subscription. Please upgrade your plan."
}

INSUFFICIENT_CREDITS

Status HTTP: 403Sua conta não possui créditos suficientes para processar esta solicitação.Solução: Compre mais créditos ou faça upgrade do seu plano de assinatura.

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits to process this file. Please add more credits to your account."
}

Erros de Validação de Arquivo

FILE_REQUIRED

Status HTTP: 400Nenhum arquivo foi enviado com a solicitação.Solução: Inclua um arquivo no campo file dos dados do seu formulário multipart.

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

INVALID_FILE_TYPE

Status HTTP: 400O tipo de arquivo enviado não é suportado.Solução: Envie um arquivo em um dos formatos suportados (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: 413O arquivo enviado excede o limite permitido para a assinatura autenticada: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB ou Enterprise 60 GB.Solução: Verifique o limite do seu plano e, em seguida, comprima o arquivo, divida-o em segmentos menores ou faça upgrade do seu plano.

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

DURATION_DETECTION_FAILED

Status HTTP: 400Não foi possível detectar a duração do arquivo enviado.Solução: Certifique-se de que o arquivo seja um arquivo de áudio ou vídeo válido e não corrompido.

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

Erros de Validação

INVALID_TARGET_LANGUAGE

Status HTTP: 400O idioma de destino especificado não é suportado.Solução: Use um dos idiomas suportados.

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

INVALID_BOOLEAN_VALUE

Status HTTP: 400Um parâmetro booleano recebeu um valor inválido.Solução: Use true ou false (como strings em form-data).

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

INVALID_JSON_FORMAT

Status HTTP: 400Um parâmetro JSON não pôde ser analisado.Solução: Certifique-se de que a string JSON esteja formatada corretamente.

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

INVALID_NUMBER_VALUE

Status HTTP: 400Um campo numérico opcional de form-data não era um número válido. Envie um valor numérico dentro do intervalo documentado.

LIPSYNC_VIDEO_TOO_LONG

Status HTTP: 400A sincronização labial foi solicitada para mídia com duração superior à suportada.Solução: Omita lipsyncPro para esta solicitação ou envie um arquivo de mídia dentro do limite de sincronização labial.

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

Erros de Recurso

PROJECT_NOT_FOUND

Status HTTP: 404O projeto especificado não existe.Solução: Verifique se o ID do projeto está correto.

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

FORBIDDEN

Status HTTP: 403Você não tem permissão para acessar este recurso.Solução: Certifique-se de estar usando a chave de API correta para este projeto.

{
  "code": "FORBIDDEN",
  "message": "You do not have permission to access this project."
}

Limitação de Taxa

RATE_LIMIT_EXCEEDED

Status HTTP: 429Você excedeu o limite de taxa para este endpoint.Solução: Aguarde antes de fazer solicitações adicionais. Use backoff exponencial.

Endpoint	Limite de Taxa
`POST /v1/translate`	10 solicitações por minuto
`POST /v1/projects`	10 solicitações por minuto
`GET /v1/translate/{id}/status`	30 solicitações por minuto
`GET /v1/projects/{id}`	20 solicitações por minuto
`DELETE /v1/translate/{id}`	10 solicitações por minuto

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait before trying again."
}

CONCURRENT_TRANSLATION_LIMIT_REACHED

Status HTTP: 429Você já atingiu o número máximo de traduções em execução em paralelo.Solução: Aguarde uma de suas traduções em andamento terminar e tente novamente a solicitação.

{
  "code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
  "message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
}

Erros de Processamento

Estes erros podem ser retornados no campo error ao verificar o status da tradução:

TRANSCRIPTION_FAILED

O áudio não pôde ser transcrito.Causas possíveis:

A qualidade do áudio está muito baixa
Nenhuma fala detectada no áudio
Codificação de áudio não suportada

{
  "code": "TRANSCRIPTION_FAILED",
  "message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}

TRANSLATION_FAILED

A transcrição não pôde ser traduzida.Causas possíveis:

Par de idiomas não suportado
O conteúdo não pôde ser processado

{
  "code": "TRANSLATION_FAILED",
  "message": "Failed to translate the content. Please try again."
}

VOICE_SYNTHESIS_FAILED

A síntese de voz falhou durante a dublagem.Causas possíveis:

A clonagem de voz falhou
Erro na geração de áudio

{
  "code": "VOICE_SYNTHESIS_FAILED",
  "message": "Failed to generate the dubbed audio. Please try again."
}

LIPSYNC_FAILED

O processamento da sincronização labial falhou.Causas possíveis:

Erro do provedor de sincronização labial
Mídia inválida ou não suportada
A solicitação foi rejeitada ou cancelada

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync failed."
}

Erros de Servidor

INTERNAL_ERROR

Status HTTP: 500Ocorreu um erro inesperado em nossos servidores.Solução: Tente novamente a solicitação. Se o problema persistir, entre em contato com o suporte.

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

Tratamento de Erros

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

Visão geral

Transcrição

Tradução

Referência

Códigos de Erro

Códigos de Erro

Formato de Resposta de Erro

Códigos de Status HTTP

Erros de transcrição e exportação de transcrição

Erros de opção de dublagem

Erros de Autenticação

Erros de Validação de Arquivo

Erros de Validação

Erros de Recurso

Limitação de Taxa

Erros de Processamento

Erros de Servidor

Tratamento de Erros

​Códigos de Erro

​Formato de Resposta de Erro

​Códigos de Status HTTP

​Erros de transcrição e exportação de transcrição

​Erros de opção de dublagem

​Erros de Autenticação

​Erros de Validação de Arquivo

​Erros de Validação

​Erros de Recurso

​Limitação de Taxa

​Erros de Processamento

​Erros de Servidor

​Tratamento de Erros

Códigos de Erro

Formato de Resposta de Erro

Códigos de Status HTTP

Erros de transcrição e exportação de transcrição

Erros de opção de dublagem

Erros de Autenticação

Erros de Validação de Arquivo

Erros de Validação

Erros de Recurso

Limitação de Taxa

Erros de Processamento

Erros de Servidor

Tratamento de Erros