> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vmeg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Business codes in Open API responses

export const productUrls = JSON.parse('{"home":"https://www.vmeg.ai/home","apiConfiguration":"https://www.vmeg.ai/open-api-setting","signIn":"https://www.vmeg.ai/signIn?redirect=%2Fhome","signInToApiSettings":"https://www.vmeg.ai/signIn?redirect=%2Fopen-api-setting","signUp":"https://www.vmeg.ai/signup","account":"https://www.vmeg.ai/account","helpCenter":"https://www.vmeg.ai/help-center/","pricing":"https://www.vmeg.ai/pricing","myTasks":"https://www.vmeg.ai/my-tasks","myAssets":"https://www.vmeg.ai/my-assets","videoTranslation":"https://www.vmeg.ai/translation","audioTranslation":"https://www.vmeg.ai/audio-translation","cloneVoice":"https://www.vmeg.ai/clone-voice","bookDemo":"https://www.vmeg.ai/book-a-demo/","contactUs":"https://www.vmeg.ai/contact-us/","apiDocs":"https://docs.vmeg.ai"}');

The Open API uses the JSON **`code`** field for business outcomes. HTTP status handles transport (for example `401` for auth failures), but success and failure semantics are defined by `code`.

## Code reference

| code | Name                  | Description                          |
| ---- | --------------------- | ------------------------------------ |
| 200  | Success               | Request succeeded                    |
| 400  | Bad Request           | Invalid or failed validation         |
| 401  | Unauthorized          | API Key missing or invalid           |
| 402  | Payment Required      | Insufficient credits or quota        |
| 404  | Not Found             | Resource not found                   |
| 409  | Conflict              | Idempotency key already used         |
| 413  | Payload Too Large     | Upload or body exceeds limit         |
| 422  | Unprocessable Entity  | Valid format but cannot be processed |
| 500  | Internal Server Error | Server error                         |
| 502  | Bad Gateway           | Upstream processing failure          |

## Response shape

```json theme={null}
{
  "code": 402,
  "message": "Insufficient quota",
  "data": null
}
```

* Success: `code === 200`, payload in `data`
* Failure: human-readable `message` for logs and support

## Common cases

<AccordionGroup>
  <Accordion title="409 Idempotency conflict">
    Returned when the same `X-Idempotency-Key` is reused on a mutating POST endpoint within the idempotency TTL. The response may include `Retry-After: 2`. See [Idempotency](/guides/idempotency).
  </Accordion>

  <Accordion title="402 Insufficient quota">
    Returned when a task cannot deduct project credits (TTS, translation, voice clone, media translation). See [Pricing](/guides/pricing) or <a href={productUrls.pricing}>add credits</a> on vmeg.ai.
  </Accordion>

  <Accordion title="502 Upstream failure">
    An upstream service failed or timed out. Poll `GET /openapi/v1/tasks/detail` with the `taskId` (your task list on vmeg.ai does not include Open API jobs). If a webhook is configured, wait for retries.
  </Accordion>

  <Accordion title="TTS voice validation (400)">
    Returned when `data[].voiceId` fails batch rules. Common `message` patterns:

    * **Unknown voiceId** — `voiceId not found in system or clone voice library: data[0] ... Use POST /openapi/v1/assets/voice/basic/list for system voices or POST /openapi/v1/assets/voice/clone/list for clone voices.`
    * **Mixed voices in one batch** — `all voiceId in one batch must share the same provider, but found multiple: S1, S2. Please use voices from the same provider, or split into separate requests.`
    * **`timbreRefAudio` with system preset** — `timbreRefAudio requires a clone provider (V1-V5), but voiceId in this batch resolved to a system provider (S1). ...`

    See [Text to speech](/guides/products/text-to-speech) and [Supported clone methods](/guides/supported-clone-methods#text-to-speech-voiceid-and-provider).
  </Accordion>
</AccordionGroup>