Skip to main content

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

​
Authentication Errors

HTTP Status: 401The provided API key is invalid, expired, or missing.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."
}
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."
}
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

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

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, ..."
}
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\"."
}
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."
}

​
Resource Errors

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

HTTP Status: 429You’ve exceeded the rate limit for this endpoint.Solution: Wait before making additional requests. Use exponential backoff.
EndpointRate Limit
POST /v1/translate5 requests per minute
GET /v1/translate/{id}/status30 requests per minute
{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait before trying again."
}

​
Processing Errors

These errors may be returned in the error field when checking translation status:
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."
}
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 during dubbing.Possible causes:
  • Voice cloning failed
  • Audio generation error
{
  "code": "VOICE_SYNTHESIS_FAILED",
  "message": "Failed to generate the dubbed audio. Please try again."
}

​
Server Errors

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 'INVALID_API_KEY':
        // Handle invalid API key
        break;
      case 'INSUFFICIENT_CREDITS':
        // Prompt user to add credits
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Implement backoff and retry
        break;
      default:
        // Handle other errors
        console.error(`Error: ${error.message}`);
    }
  }
} catch (err) {
  // Handle network errors
}