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

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

<AccordionGroup>
  <Accordion title="MISSING_API_KEY" icon="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>

  <Accordion title="INVALID_API_KEY_FORMAT" icon="key">
    **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>

  <Accordion title="INVALID_API_KEY" icon="key">
    **HTTP Status:** 401

    The provided API key is invalid or expired.

    **Solution:** Check that your API key is correct and included in the `x-api-key` header.

    ```json theme={null}
    {
      "code": "INVALID_API_KEY",
      "message": "The provided API key is invalid. Please check your API key and try again."
    }
    ```
  </Accordion>

  <Accordion title="API_ACCESS_REQUIRED" icon="key">
    **HTTP Status:** 403

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

    ```json theme={null}
    {
      "code": "API_ACCESS_REQUIRED",
      "message": "API access is required. Please request access to the API beta program."
    }
    ```
  </Accordion>

  <Accordion title="SUBSCRIPTION_REQUIRED" icon="credit-card">
    **HTTP Status:** 403

    API access requires an active paid subscription.

    **Solution:** Upgrade to a paid plan at [voicecheap.ai](https://voicecheap.ai/pricing).

    ```json theme={null}
    {
      "code": "SUBSCRIPTION_REQUIRED",
      "message": "API access requires an active paid subscription. Please upgrade your plan."
    }
    ```
  </Accordion>

  <Accordion title="INSUFFICIENT_CREDITS" icon="coins">
    **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."
    }
    ```
  </Accordion>
</AccordionGroup>

## File Validation Errors

<AccordionGroup>
  <Accordion title="FILE_REQUIRED" icon="file">
    **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>

  <Accordion title="INVALID_FILE_TYPE" icon="file-circle-xmark">
    **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>

  <Accordion title="FILE_TOO_LARGE" icon="weight-hanging">
    **HTTP Status:** 400

    The uploaded file exceeds the maximum allowed size (20 GB).

    **Solution:** Compress your file or split it into smaller segments.

    ```json theme={null}
    {
      "code": "FILE_TOO_LARGE",
      "message": "File size exceeds maximum allowed size of 20GB"
    }
    ```
  </Accordion>

  <Accordion title="DURATION_DETECTION_FAILED" icon="clock">
    **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."
    }
    ```
  </Accordion>
</AccordionGroup>

## Validation Errors

<AccordionGroup>
  <Accordion title="INVALID_TARGET_LANGUAGE" icon="language">
    **HTTP Status:** 400

    The specified target language is not supported.

    **Solution:** Use one of the [supported languages](/docs/introduction#supported-languages).

    ```json theme={null}
    {
      "code": "VALIDATION_ERROR",
      "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
    }
    ```
  </Accordion>

  <Accordion title="INVALID_BOOLEAN_VALUE" icon="toggle-off">
    **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>

  <Accordion title="INVALID_JSON_FORMAT" icon="code">
    **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>

  <Accordion title="LIPSYNC_VIDEO_TOO_LONG" icon="film">
    **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 30 minutes. Your video is 45 minutes long."
    }
    ```
  </Accordion>
</AccordionGroup>

## Resource Errors

<AccordionGroup>
  <Accordion title="PROJECT_NOT_FOUND" icon="folder-open">
    **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>

  <Accordion title="FORBIDDEN" icon="ban">
    **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."
    }
    ```
  </Accordion>
</AccordionGroup>

## Rate Limiting

<AccordionGroup>
  <Accordion title="RATE_LIMIT_EXCEEDED" icon="gauge-high">
    **HTTP Status:** 429

    You'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 |

    ```json theme={null}
    {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Too many requests. Please wait before trying again."
    }
    ```
  </Accordion>

  <Accordion title="CONCURRENT_TRANSLATION_LIMIT_REACHED" icon="gauge-high">
    **HTTP Status:** 429

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

    ```json theme={null}
    {
      "code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
      "message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
    }
    ```
  </Accordion>
</AccordionGroup>

## Processing Errors

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

<AccordionGroup>
  <Accordion title="TRANSCRIPTION_FAILED" icon="microphone-slash">
    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": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
    }
    ```
  </Accordion>

  <Accordion title="TRANSLATION_FAILED" icon="language">
    The transcription could not be translated.

    **Possible causes:**

    * Unsupported language pair
    * Content could not be processed

    ```json theme={null}
    {
      "code": "TRANSLATION_FAILED",
      "message": "Failed to translate the content. Please try again."
    }
    ```
  </Accordion>

  <Accordion title="VOICE_SYNTHESIS_FAILED" icon="waveform">
    Voice synthesis failed during dubbing.

    **Possible causes:**

    * Voice cloning failed
    * Audio generation error

    ```json theme={null}
    {
      "code": "VOICE_SYNTHESIS_FAILED",
      "message": "Failed to generate the dubbed audio. Please try again."
    }
    ```
  </Accordion>

  <Accordion title="LIPSYNC_FAILED" icon="film">
    Lip sync processing failed.

    **Possible causes:**

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

    ```json theme={null}
    {
      "code": "LIPSYNC_FAILED",
      "message": "Lip sync failed."
    }
    ```
  </Accordion>
</AccordionGroup>

## Server Errors

<AccordionGroup>
  <Accordion title="INTERNAL_ERROR" icon="server">
    **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."
    }
    ```
  </Accordion>
</AccordionGroup>

## Handling Errors

<CodeGroup>
  ```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}")
  ```
</CodeGroup>