> ## 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.

# Códigos de Erro

> Referência completa dos códigos de erro retornados pela API VoiceCheap

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

```json theme={null}
{
  "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:

```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"]
    }
  ]
}
```

## 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

> [accordion] MISSING\_API\_KEY
>
> **Status HTTP:** 401
>
> O cabeçalho `x-api-key` não foi fornecido.
>
> **Solução:** Inclua sua chave de API no cabeçalho `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
>
> A chave de API não utiliza o prefixo `vc_` esperado.
>
> **Solução:** Verifique se você copiou a chave completa do aplicativo 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
>
> A 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`.
>
> ```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
>
> O 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](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
>
> Sua 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.
>
> ```json theme={null}
> {
>   "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

> [accordion] FILE\_REQUIRED
>
> **Status HTTP:** 400
>
> Nenhum arquivo foi enviado com a solicitação.
>
> **Solução:** Inclua um arquivo no campo `file` dos dados do seu formulário 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
>
> O 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).
>
> ```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
>
> O 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.
>
> ```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
>
> Nã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.
>
> ```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."
> }
> ```

## Erros de Validação

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **Status HTTP:** 400
>
> O idioma de destino especificado não é suportado.
>
> **Solução:** Use um dos [idiomas suportados](https://api-docs.voicecheap.ai/docs/pt/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
>
> Um parâmetro booleano recebeu um valor inválido.
>
> **Solução:** Use `true` ou `false` (como strings em 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
>
> Um parâmetro JSON não pôde ser analisado.
>
> **Solução:** Certifique-se de que a string JSON esteja formatada corretamente.
>
> ```json theme={null}
> {
>   "code": "INVALID_JSON_FORMAT",
>   "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **Status HTTP:** 400
>
> Um campo numérico opcional de form-data não era um número válido. Envie um valor numérico dentro do intervalo documentado.

> [accordion] LIPSYNC\_VIDEO\_TOO\_LONG
>
> **Status HTTP:** 400
>
> A 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.
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_VIDEO_TOO_LONG",
>   "message": "LipSync supports up to 180 minutes. Your video is 181 minutes long."
> }
> ```

## Erros de Recurso

> [accordion] PROJECT\_NOT\_FOUND
>
> **Status HTTP:** 404
>
> O projeto especificado não existe.
>
> **Solução:** Verifique se o ID do projeto está correto.
>
> ```json theme={null}
> {
>   "code": "PROJECT_NOT_FOUND",
>   "message": "Project with ID 'abc123' not found."
> }
> ```

> [accordion] FORBIDDEN
>
> **Status HTTP:** 403
>
> Você não tem permissão para acessar este recurso.
>
> **Solução:** Certifique-se de estar usando a chave de API correta para este projeto.
>
> ```json theme={null}
> {
>   "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](https://api-docs.voicecheap.ai/docs/pt/api-reference/limits.md) 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:

> [accordion] 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
>
> ```json theme={null}
> {
>   "code": "TRANSCRIPTION_FAILED",
>   "message": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] 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
>
> ```json theme={null}
> {
>   "code": "TRANSLATION_FAILED",
>   "message": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] 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
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## Erros de Servidor

> [accordion] INTERNAL\_ERROR
>
> **Status HTTP:** 500
>
> Ocorreu um erro inesperado em nossos servidores.
>
> **Solução:** Tente novamente a solicitação. Se o problema persistir, entre em contato com o suporte.
>
> ```json theme={null}
> {
>   "code": "INTERNAL_ERROR",
>   "message": "An unexpected error occurred. Please try again later."
> }
> ```

## Tratamento de Erros

```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.