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. Request payload validation failures return one entry per invalid field in details, and field is omitted when the constraint message does not name a specific property:

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": [
    {
      "field": "outputFormat",
      "messages": ["outputFormat must be one of the following values: json, srt, vtt"]
    }
  ]
}

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
409	Conflict - The project is not in a state that allows the request
413	Payload Too Large - Uploaded file exceeds its limit
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end
502	Bad Gateway - Transcription could not finish

Transcription and transcript export errors

Status	Code	Meaning
400	`INVALID_MEDIA_STREAM`	Uploaded media does not contain an audio stream
400	`DURATION_TOO_LONG`	Standalone transcription media is longer than two hours
400	`INVALID_BRAND_VOCABULARY`	A request-specific vocabulary entry violates the limits
400	`TARGET_LANGUAGE_REQUIRED`	A translated transcript request omitted its language
404	`TRANSCRIPT_NOT_FOUND`	Requested original or translated transcript is absent
409	`TRANSCRIPT_NOT_READY`	Requested transcript is still processing
502	`TRANSCRIPTION_EMPTY`	The transcription contained no usable speech
502	`TRANSCRIPTION_FAILED`	The transcription could not complete
400	`INVALID_MULTIPART_REQUEST`	The multipart upload request is malformed or exceeds limits

Dubbing option errors

Status	Code	Meaning
400	`INVALID_SOURCE_SRT`	sourceSrt does not contain valid SRT cues
400	`SOURCE_LANGUAGE_REQUIRED_FOR_SRT`	sourceSrt requires an explicit originalLanguage
400	`INVALID_TRANSLATED_SRT`	translatedSrt does not contain valid SRT cues
400	`TRANSLATED_SRT_CUE_COUNT_MISMATCH`	translatedSrt and sourceSrt cue counts differ
409	`DUB_ONLY_REQUIRES_TRANSCRIPTION`	The project has no completed transcription to dub
409	`TRANSLATION_ALREADY_IN_PROGRESS`	A dubbing run is already in progress for the language
400	`VOICE_ID_REQUIRED`	Custom voice mode requires a voice ID
400	`VOICE_ID_NOT_ALLOWED_WITH_CLONING`	voiceId was combined with voice cloning
400	`VOICE_CLONING_SETTINGS_NOT_ALLOWED`	Clone settings were combined with custom voice mode
400	`CONFLICTING_LIPSYNC_OPTIONS`	Modern and legacy lip-sync fields disagree
400	`TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND`	Time skips require background audio
400	`TRANSLATION_TIME_SKIP_CONFLICT`	Time skips conflict with original-voice retention
400	`TRANSLATION_TIME_SKIP_OUT_OF_RANGE`	A time skip extends beyond the media duration
400	`INVALID_TRANSLATION_TIME_SKIPS`	A time skip overlaps a transcription segment
400	`SUBTITLES_NOT_AVAILABLE_FOR_AUDIO`	Burned-in subtitles require video input
400	`LIPSYNC_NOT_AVAILABLE_FOR_AUDIO`	Lip sync requires video input
400	`TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO`	Translation time skips require video input
403	`CUSTOM_VOICE_ACCESS_DENIED`	The selected voice is neither a catalog voice nor a custom voice saved by the authenticated account.
403	`LIPSYNC_MODE_ACCESS_DENIED`	Premium lip-sync mode is unavailable on the plan

Asynchronous SRT alignment errors

These errors occur after a translation or dub request has been accepted. The status endpoint responds with HTTP 200 and status: "failed"; its error and the project.translation.failed webhook contain only code and message. Stored failures use fixed VoiceCheap messages; cue numbers and segment indexes are not included. Synchronous request errors, including TRANSLATED_SRT_CUE_COUNT_MISMATCH, remain HTTP 400 above.

Result	Code	Meaning
`GET` 200 / webhook	`TRANSLATED_SRT_UNMATCHED_CUES`	A translated cue matches no transcript segment (reported by status and webhooks)
`GET` 200 / webhook	`TRANSLATED_SRT_MISSING_SEGMENTS`	A transcript segment has no translated cue (reported by status and webhooks)

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.Solution: Check that your API key is correct and included in the x-api-key header.

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

SUBSCRIPTION_REQUIRED

HTTP Status: 403API and MCP access require a Starter plan or higher.Solution: Upgrade to a Starter plan or higher at 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

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

Other authentication and team errors

HTTP	Code	Description
401	`USER_NOT_FOUND`	The account linked to this key was not found
403	`AMBIGUOUS_TEAM_API_KEY`	The key holder belongs to multiple teams; contact support
403	`TEAM_OWNER_NOT_FOUND`	The linked team owner account was not found

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: 413The uploaded file exceeds the allowance for the authenticated subscription: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB, or Enterprise 60 GB.Solution: Check your plan limit, then compress the file, split it into smaller segments, or upgrade your plan.

{
  "code": "FILE_TOO_LARGE",
  "message": "File size exceeds the 5GB limit for the beginner plan.",
  "maximumFileSizeBytes": 5368709120
}

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

INVALID_NUMBER_VALUE

HTTP Status: 400An optional numeric form-data field was not a valid number. Send a numeric value within the documented range.

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

Permissions and usage errors

Status	Code	Action
401	`API_KEY_EXPIRED`, `INVALID_MCP_TOKEN`	Use a valid, unexpired key or reconnect the assistant.
403	`INSUFFICIENT_SCOPE`	Grant the required permission or choose another credential.
403	`SUBSCRIPTION_REQUIRED`	Use a Starter plan or higher.
429	`INTEGRATION_MONTHLY_LIMIT_REACHED`	Wait for the monthly reset or change plan.
429	`INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED`	Wait before retrying and use backoff.
429	`CONCURRENT_TRANSLATION_LIMIT_REACHED`	Wait for an in-progress generation to finish.
400	`VALIDATION_ERROR`	Correct the arguments using the catalog input schema.
404	`UNKNOWN_ACTION`	Use a supported action name from discovery.

See usage and limits for the shared account allowance. Errors do not consume monthly calls. action_request_get, usage_get, projects_status, and GET /v1/translate/{projectId}/status are exempt from the monthly allowance.

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

TRANSLATION_FAILED

The transcription could not be translated.Possible causes:

Unsupported language pair
Content could not be processed

{
  "code": "TRANSLATION_FAILED",
  "message": "The translation could not be completed. Please try again."
}

LIPSYNC_FAILED

Lip sync processing failed.Possible causes:

A temporary lip-sync processing problem
Invalid or unsupported media
Request was rejected or canceled

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

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

Discovery

Account

Usage and activity

Settings and notifications

Team

Projects

Translation and dubbing

Transcripts and editing

Text to speech

Speech voices

Dubbing voices

Transcription

Subtitles and captions

Images

Thumbnails

Folders

Glossary

Webhooks

Publishing

Request status

OAuth and MCP protocol

Error Codes

Error Codes

Error Response Format

HTTP Status Codes

Transcription and transcript export errors

Dubbing option errors

Asynchronous SRT alignment errors

Authentication Errors

Other authentication and team errors

File Validation Errors

Validation Errors

Resource Errors

Permissions and usage errors

Processing Errors

Server Errors

Handling Errors

​Error Codes

​Error Response Format

​HTTP Status Codes

​Transcription and transcript export errors

​Dubbing option errors

​Asynchronous SRT alignment errors

​Authentication Errors

​Other authentication and team errors

​File Validation Errors

​Validation Errors

​Resource Errors

​Permissions and usage errors

​Processing Errors

​Server Errors

​Handling Errors

Error Codes

Error Response Format

HTTP Status Codes

Transcription and transcript export errors

Dubbing option errors

Asynchronous SRT alignment errors

Authentication Errors

Other authentication and team errors

File Validation Errors

Validation Errors

Resource Errors

Permissions and usage errors

Processing Errors

Server Errors

Handling Errors