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

# 错误码

> Open API 响应中的业务码

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"}');

Open API 使用 JSON 字段 **`code`** 表示业务结果。HTTP 状态码用于传输层（例如认证失败为 `401`），成功与否以 `code` 为准。

## 码表

| code | 名称                    | 说明            |
| ---- | --------------------- | ------------- |
| 200  | Success               | 请求成功          |
| 400  | Bad Request           | 参数无效或校验失败     |
| 401  | Unauthorized          | API Key 缺失或无效 |
| 402  | Payment Required      | 积分或配额不足       |
| 404  | Not Found             | 资源不存在         |
| 409  | Conflict              | 幂等键已被使用       |
| 413  | Payload Too Large     | 上传或请求体超限      |
| 422  | Unprocessable Entity  | 格式正确但无法处理     |
| 500  | Internal Server Error | 服务端错误         |
| 502  | Bad Gateway           | 上游处理失败        |

## 响应结构

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

* 成功：`code === 200`，载荷在 `data`
* 失败：`message` 供日志与支持排查

## 常见场景

<AccordionGroup>
  <Accordion title="409 幂等冲突">
    同一 `X-Idempotency-Key` 在幂等 POST 接口的 TTL 内重复使用时返回。响应可能包含 `Retry-After: 2`。见 [幂等](/zh/guides/idempotency)。
  </Accordion>

  <Accordion title="402 配额不足">
    任务无法扣减项目积分时返回。见 [价格](/zh/guides/pricing) 或在 vmeg.ai <a href={productUrls.pricing}>价格页</a> 充值。
  </Accordion>

  <Accordion title="502 上游失败">
    上游服务调用失败或超时。使用 `taskId` 轮询 `GET /openapi/v1/tasks/detail`（vmeg.ai 网页任务记录不包含 Open API 任务）；若已配置 Webhook，可等待重试。
  </Accordion>

  <Accordion title="TTS 音色校验（400）">
    `data[].voiceId` 不符合批处理规则时返回。常见 `message` 模式：

    * **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.`
    * **同批音色不兼容** — `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 混批** — `timbreRefAudio requires a clone provider (V1-V5), but voiceId in this batch resolved to a system provider (S1). ...`

    见 [文本转语音](/zh/guides/products/text-to-speech) 与 [支持的克隆方式](/zh/guides/supported-clone-methods#文本转语音voiceid-与组批规则)。
  </Accordion>
</AccordionGroup>