Error Codes

The VoiceCheap API uses standard HTTP status codes and returns structured error responses to help you handle errors gracefully.

Error Response Format

All error responses follow this structure:

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

Some errors may include additional fields:

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": {
    "field": "targetLanguage",
    "reason": "Invalid target language. Allowed languages: english, spanish, ..."
  }
}

HTTP Status Codes

Status Code	Meaning
200	OK - Request succeeded
400	Bad Request - Invalid parameters or validation error
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key but insufficient permissions
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Authentication Errors

MISSING_API_KEY

HTTP Status: 401The x-api-key header was not provided.Solution: Include your API key in the x-api-key header.

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

INVALID_API_KEY_FORMAT

HTTP Status: 401The API key does not use the expected vc_ prefix.Solution: Check that you copied the full key from the VoiceCheap app.

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

INVALID_API_KEY

HTTP Status: 401The provided API key is invalid or expired.Solution: Check that your API key is correct and included in the x-api-key header.

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

API_ACCESS_REQUIRED

HTTP Status: 403The account has a valid key, but API access is not enabled for that account.Solution: Request API access or use an account that already has API access enabled.

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

SUBSCRIPTION_REQUIRED

HTTP Status: 403API access requires an active paid subscription.Solution: Upgrade to a paid plan at voicecheap.ai.

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

INSUFFICIENT_CREDITS

HTTP Status: 403Your account doesn’t have enough credits to process this request.Solution: Purchase more credits or upgrade your subscription plan.

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

File Validation Errors

FILE_REQUIRED

HTTP Status: 400No file was uploaded with the request.Solution: Include a file in the file field of your multipart form data.

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

INVALID_FILE_TYPE

HTTP Status: 400The uploaded file type is not supported.Solution: Upload a file in one of the supported formats (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

HTTP Status: 400The uploaded file exceeds the maximum allowed size (20 GB).Solution: Compress your file or split it into smaller segments.

{
  "code": "FILE_TOO_LARGE",
  "message": "File size exceeds maximum allowed size of 20GB"
}

DURATION_DETECTION_FAILED

HTTP Status: 400Could not detect the duration of the uploaded file.Solution: Ensure the file is a valid, non-corrupted video or audio file.

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

Validation Errors

INVALID_TARGET_LANGUAGE

HTTP Status: 400The specified target language is not supported.Solution: Use one of the supported languages.

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

INVALID_BOOLEAN_VALUE

HTTP Status: 400A boolean parameter received an invalid value.Solution: Use true or false (as strings in form-data).

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

INVALID_JSON_FORMAT

HTTP Status: 400A JSON parameter could not be parsed.Solution: Ensure the JSON string is properly formatted.

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

LIPSYNC_VIDEO_TOO_LONG

HTTP Status: 400Lip-sync was requested for media longer than the supported lip-sync duration.Solution: Omit lipsyncPro for this request, or submit a media file within the lip-sync limit.

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

Resource Errors

PROJECT_NOT_FOUND

HTTP Status: 404The specified project does not exist.Solution: Verify the project ID is correct.

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

FORBIDDEN

HTTP Status: 403You don’t have permission to access this resource.Solution: Ensure you’re using the correct API key for this project.

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

Rate Limiting

RATE_LIMIT_EXCEEDED

HTTP Status: 429You’ve exceeded the rate limit for this endpoint.Solution: Wait before making additional requests. Use exponential backoff.

Endpoint	Rate Limit
`POST /v1/translate`	10 requests per minute
`POST /v1/projects`	10 requests per minute
`GET /v1/translate/{id}/status`	30 requests per minute
`GET /v1/projects/{id}`	20 requests per minute
`DELETE /v1/translate/{id}`	10 requests per minute

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

CONCURRENT_TRANSLATION_LIMIT_REACHED

HTTP Status: 429You already have the maximum number of translations running in parallel.Solution: Wait for one of your in-progress translations to finish, then retry the request.

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

Processing Errors

These errors may be returned in the error field when checking translation status:

TRANSCRIPTION_FAILED

The audio could not be transcribed.Possible causes:

Audio quality is too low
No speech detected in the audio
Unsupported audio encoding

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

TRANSLATION_FAILED

The transcription could not be translated.Possible causes:

Unsupported language pair
Content could not be processed

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

VOICE_SYNTHESIS_FAILED

Voice synthesis failed during dubbing.Possible causes:

Voice cloning failed
Audio generation error

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

LIPSYNC_FAILED

Lip sync processing failed.Possible causes:

Lip sync provider error
Invalid or unsupported media
Request was rejected or canceled

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

Server Errors

INTERNAL_ERROR

HTTP Status: 500An unexpected error occurred on our servers.Solution: Retry the request. If the problem persists, contact support.

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

Handling Errors

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

Overview

Translation

Reference

Error Codes

Error Codes

Error Response Format

HTTP Status Codes

Authentication Errors

File Validation Errors

Validation Errors

Resource Errors

Rate Limiting

Processing Errors

Server Errors

Handling Errors

​Error Codes

​Error Response Format

​HTTP Status Codes

​Authentication Errors

​File Validation Errors

​Validation Errors

​Resource Errors

​Rate Limiting

​Processing Errors

​Server Errors

​Handling Errors

Error Codes

Error Response Format

HTTP Status Codes

Authentication Errors

File Validation Errors

Validation Errors

Resource Errors

Rate Limiting

Processing Errors

Server Errors

Handling Errors