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 projeto não está em um estado que permita a solicitação
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 - Não foi possível concluir a transcrição

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`	Não foi possível concluir a transcriçã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	`INVALID_TRANSLATED_SRT`	translatedSrt não contém cues SRT válidos
400	`TRANSLATED_SRT_CUE_COUNT_MISMATCH`	A quantidade de cues de translatedSrt e sourceSrt é diferente
409	`DUB_ONLY_REQUIRES_TRANSCRIPTION`	O projeto não tem uma transcrição concluída para dublar
409	`TRANSLATION_ALREADY_IN_PROGRESS`	Já existe uma dublagem em andamento para o idioma
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 selecionada não é uma voz do catálogo nem uma voz personalizada salva pela conta autenticada.
403	`LIPSYNC_MODE_ACCESS_DENIED`	O modo de sincronização labial premium não está disponível no plano

Erros assíncronos de alinhamento SRT

Estes erros ocorrem depois de um pedido de tradução ou dublagem ter sido aceite. O endpoint de status responde com HTTP 200 e status: "failed"; o respetivo error e o webhook project.translation.failed contêm apenas code e message. As falhas salvas usam mensagens fixas da VoiceCheap; números de cues e índices dos segmentos não são incluídos. Os erros síncronos do pedido, incluindo TRANSLATED_SRT_CUE_COUNT_MISMATCH, continuam a ser HTTP 400 na tabela acima.

Resultado	Code	Significado
`GET` 200 / webhook	`TRANSLATED_SRT_UNMATCHED_CUES`	Um cue traduzido não corresponde a nenhum segmento da transcrição (reportado no status e nos webhooks)
`GET` 200 / webhook	`TRANSLATED_SRT_MISSING_SEGMENTS`	Um segmento da transcrição não tem cue traduzido (reportado no status e nos webhooks)

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.Solução: Verifique se sua chave de API está correta e incluída no cabeçalho x-api-key.

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

SUBSCRIPTION_REQUIRED

Status HTTP: 403O acesso à API e ao MCP requer um plano Starter ou superior.Solução: Faça upgrade para um plano Starter ou superior em 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: 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."
}

Outros erros de autenticação e equipa

HTTP	Código	Descrição
401	`USER_NOT_FOUND`	Não foi encontrada a conta associada a esta chave
403	`AMBIGUOUS_TEAM_API_KEY`	O titular da chave pertence a várias equipas; contacte o suporte
403	`TEAM_OWNER_NOT_FOUND`	Não foi encontrada a conta do proprietário da equipa associada

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 180 minutes. Your video is 181 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."
}

Erros de permissão e uso

Status	Código	Ação
401	`API_KEY_EXPIRED`, `INVALID_MCP_TOKEN`	Use uma chave válida e não expirada ou reconecte o assistente.
403	`INSUFFICIENT_SCOPE`	Conceda a permissão necessária ou escolha outra credencial.
403	`SUBSCRIPTION_REQUIRED`	Use um plano Starter ou superior.
429	`INTEGRATION_MONTHLY_LIMIT_REACHED`	Aguarde a renovação mensal ou mude de plano.
429	`INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED`	Aguarde antes de tentar novamente e aumente progressivamente o intervalo entre tentativas.
429	`CONCURRENT_TRANSLATION_LIMIT_REACHED`	Aguarde a conclusão de uma geração em andamento.
400	`VALIDATION_ERROR`	Corrija os argumentos usando o esquema de entrada do catálogo.
404	`UNKNOWN_ACTION`	Use um nome de ação aceito retornado pela descoberta.

Consulte uso e limites para conhecer a cota compartilhada da conta. Erros não consomem chamadas mensais. action_request_get, usage_get, projects_status e GET /v1/translate/{projectId}/status são isentas da cota mensal.

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": "The transcription could not be completed. Please try again."
}

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": "The translation could not be completed. Please try again."
}

LIPSYNC_FAILED

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

Um problema temporário durante a sincronização labial
Mídia inválida ou não suportada
A solicitação foi rejeitada ou cancelada

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

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

Descoberta

Conta

Uso e atividade

Configurações e notificações

Equipe

Projetos

Tradução e dublagem

Transcrições e edição

Conversão de texto em fala

Vozes de fala

Vozes de dublagem

Transcrição

Legendas

Imagens

Miniaturas

Pastas

Glossário

Webhooks

Publicação

Status das requisições

OAuth e protocolo MCP

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 assíncronos de alinhamento SRT

Erros de Autenticação

Outros erros de autenticação e equipa

Erros de Validação de Arquivo

Erros de Validação

Erros de Recurso

Erros de permissão e uso

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 assíncronos de alinhamento SRT

​Erros de Autenticação

​Outros erros de autenticação e equipa

​Erros de Validação de Arquivo

​Erros de Validação

​Erros de Recurso

​Erros de permissão e uso

​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 assíncronos de alinhamento SRT

Erros de Autenticação

Outros erros de autenticação e equipa

Erros de Validação de Arquivo

Erros de Validação

Erros de Recurso

Erros de permissão e uso

Erros de Processamento

Erros de Servidor

Tratamento de Erros