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

# Error Codes

> Complete reference of error codes returned by the VoiceCheap API

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

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

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

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

> [accordion] MISSING\_API\_KEY
>
> **HTTP Status:** 401
>
> The `x-api-key` header was not provided.
>
> **Solution:** Include your API key in the `x-api-key` header.
>
> ```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
>
> **HTTP Status:** 401
>
> The API key does not use the expected `vc_` prefix.
>
> **Solution:** Check that you copied the full key from the VoiceCheap app.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY_FORMAT",
>   "message": "Invalid API key format. API keys must start with \"vc_\"."
> }
> ```

> [accordion] INVALID\_API\_KEY
>
> **HTTP Status:** 401
>
> The provided API key is invalid.
>
> **Solution:** Check that your API key is correct and included in the `x-api-key` header.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY",
>   "message": "Invalid API key. Please check your API key and try again."
> }
> ```

> [accordion] SUBSCRIPTION\_REQUIRED
>
> **HTTP Status:** 403
>
> API and MCP access require a Starter plan or higher.
>
> **Solution:** Upgrade to a Starter plan or higher at [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
>
> **HTTP Status:** 403
>
> Your account doesn't have enough credits to process this request.
>
> **Solution:** Purchase more credits or upgrade your subscription plan.
>
> ```json theme={null}
> {
>   "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

> [accordion] FILE\_REQUIRED
>
> **HTTP Status:** 400
>
> No file was uploaded with the request.
>
> **Solution:** Include a file in the `file` field of your multipart form data.
>
> ```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
>
> **HTTP Status:** 400
>
> The 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).
>
> ```json theme={null}
> {
>   "code": "INVALID_FILE_TYPE",
>   "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
> }
> ```

> [accordion] FILE\_TOO\_LARGE
>
> **HTTP Status:** 413
>
> The 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.
>
> ```json theme={null}
> {
>   "code": "FILE_TOO_LARGE",
>   "message": "File size exceeds the 5GB limit for the beginner plan.",
>   "maximumFileSizeBytes": 5368709120
> }
> ```

> [accordion] DURATION\_DETECTION\_FAILED
>
> **HTTP Status:** 400
>
> Could not detect the duration of the uploaded file.
>
> **Solution:** Ensure the file is a valid, non-corrupted video or audio file.
>
> ```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."
> }
> ```

## Validation Errors

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **HTTP Status:** 400
>
> The specified target language is not supported.
>
> **Solution:** Use one of the [supported languages](https://api-docs.voicecheap.ai/docs/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
>
> **HTTP Status:** 400
>
> A boolean parameter received an invalid value.
>
> **Solution:** Use `true` or `false` (as strings in 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
>
> **HTTP Status:** 400
>
> A JSON parameter could not be parsed.
>
> **Solution:** Ensure the JSON string is properly formatted.
>
> ```json theme={null}
> {
>   "code": "INVALID_JSON_FORMAT",
>   "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **HTTP Status:** 400
>
> An optional numeric form-data field was not a valid number. Send a numeric value within the documented range.

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

## Resource Errors

> [accordion] PROJECT\_NOT\_FOUND
>
> **HTTP Status:** 404
>
> The specified project does not exist.
>
> **Solution:** Verify the project ID is correct.
>
> ```json theme={null}
> {
>   "code": "PROJECT_NOT_FOUND",
>   "message": "Project with ID 'abc123' not found."
> }
> ```

> [accordion] FORBIDDEN
>
> **HTTP Status:** 403
>
> You don't have permission to access this resource.
>
> **Solution:** Ensure you're using the correct API key for this project.
>
> ```json theme={null}
> {
>   "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](https://api-docs.voicecheap.ai/docs/api-reference/limits.md) 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:

> [accordion] TRANSCRIPTION\_FAILED
>
> The audio could not be transcribed.
>
> **Possible causes:**
>
> * Audio quality is too low
> * No speech detected in the audio
> * Unsupported audio encoding
>
> ```json theme={null}
> {
>   "code": "TRANSCRIPTION_FAILED",
>   "message": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] TRANSLATION\_FAILED
>
> The transcription could not be translated.
>
> **Possible causes:**
>
> * Unsupported language pair
> * Content could not be processed
>
> ```json theme={null}
> {
>   "code": "TRANSLATION_FAILED",
>   "message": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] LIPSYNC\_FAILED
>
> Lip sync processing failed.
>
> **Possible causes:**
>
> * A temporary lip-sync processing problem
> * Invalid or unsupported media
> * Request was rejected or canceled
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## Server Errors

> [accordion] INTERNAL\_ERROR
>
> **HTTP Status:** 500
>
> An unexpected error occurred on our servers.
>
> **Solution:** Retry the request. If the problem persists, contact support.
>
> ```json theme={null}
> {
>   "code": "INTERNAL_ERROR",
>   "message": "An unexpected error occurred. Please try again later."
> }
> ```

## Handling Errors

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