> ## 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 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
**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."
}
```
**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_\"."
}
```
**Status HTTP:** 401
A 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`.
```json theme={null}
{
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid. Please check your API key and try again."
}
```
**Status HTTP:** 403
A 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.
```json theme={null}
{
"code": "API_ACCESS_REQUIRED",
"message": "API access is required. Please request access to the API beta program."
}
```
**Status HTTP:** 403
O acesso à API requer uma assinatura paga ativa.
**Solução:** Faça upgrade para um plano pago em [voicecheap.ai](https://voicecheap.ai/pricing).
```json theme={null}
{
"code": "SUBSCRIPTION_REQUIRED",
"message": "API access requires an active paid subscription. Please upgrade your plan."
}
```
**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."
}
```
## Erros de Validação de Arquivo
**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."
}
```
**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, ..."
}
```
**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
}
```
**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
**Status HTTP:** 400
O idioma de destino especificado não é suportado.
**Solução:** Use um dos [idiomas suportados](/docs/pt/introduction#supported-languages).
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}
```
**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\"."
}
```
**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."
}
```
**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.
**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 30 minutes. Your video is 45 minutes long."
}
```
## Erros de Recurso
**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."
}
```
**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."
}
```
## Limitação de Taxa
**Status HTTP:** 429
Você 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 |
```json theme={null}
{
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please wait before trying again."
}
```
**Status HTTP:** 429
Você 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.
```json theme={null}
{
"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:
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": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}
```
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": "Failed to translate the content. Please try again."
}
```
A síntese de voz falhou durante a dublagem.
**Causas possíveis:**
* A clonagem de voz falhou
* Erro na geração de áudio
```json theme={null}
{
"code": "VOICE_SYNTHESIS_FAILED",
"message": "Failed to generate the dubbed audio. Please try again."
}
```
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
```json theme={null}
{
"code": "LIPSYNC_FAILED",
"message": "Lip sync failed."
}
```
## Erros de Servidor
**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}")
```