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

# 错误码

> API 错误参考：HTTP 状态码、error_code 取值以及重试分类。

## 响应结构

`/v1/*`（OpenAI 兼容）：

```json theme={null}
{ "error": { "type": "invalid_request_error", "message": "...", "code": 400 } }
```

控制台 / 内部接口：

```json theme={null}
{ "code": 401, "message": "..." }
```

## HTTP 状态码

| Code  | Name                 | Meaning                 |
| ----- | -------------------- | ----------------------- |
| `200` | OK                   |                         |
| `400` | Bad Request          | 参数无效或生成仍在处理中            |
| `401` | Unauthorized         | 缺少 API key 或 API key 无效 |
| `402` | Insufficient Credits | 余额不足                    |
| `404` | Not Found            | 未知的端点或资源                |
| `422` | Validation Error     | 请求体未通过 schema 校验        |
| `429` | Rate Limited         | 退避后重试                   |
| `455` | Service Unavailable  | 维护中或上游服务中断              |
| `500` | Server Error         | 内部错误                    |
| `501` | Generation Failed    | 模型已接受请求但未产生任何输出         |
| `505` | Feature Disabled     | 端点已禁用                   |

## `error_code` 取值

一组稳定、更细粒度的类别，会设置在每一次失败的生成上。可从 `GET /logs` 读取（每行的 `error_code` 字段）。命名遵循 OpenAI 的 `error.code` 约定。

| `error_code`               | HTTP     | Retry? | Fix                                            |
| -------------------------- | -------- | ------ | ---------------------------------------------- |
| `insufficient_quota`       | 402, 455 | 否      | 前往 [/billing](https://vibetoken.cn/billing) 充值 |
| `content_policy_violation` | 400      | 否      | 改写提示词或更换输入图像                                   |
| `rate_limit_exceeded`      | 429      | 是      | 指数退避                                           |
| `timeout`                  | 455      | 是      | 重新提交；上游可能已完成                                   |
| `provider_unavailable`     | 455      | 是      | 暂时性问题 — 稍后重试                                   |
| `invalid_request_error`    | 400      | 否      | 修正参数                                           |
| `server_error`             | 500      | 是      | 重试；若持续出现请联系支持                                  |
| `internal_error`           | 500      | 是      | 重试；若可复现请上报                                     |

## 重试分类

```python theme={null}
RETRYABLE_CODES = {
    "rate_limit_exceeded",
    "timeout",
    "provider_unavailable",
    "server_error",
    "internal_error",
}

def should_retry(error_code: str | None, http_status: int) -> bool:
    if error_code in RETRYABLE_CODES:
        return True
    return http_status == 429 or http_status >= 500
```

## 退避示例

```python theme={null}
import time, requests

def post_with_retry(url, headers, body, max_retries=5):
    for attempt in range(max_retries):
        res = requests.post(url, headers=headers, json=body)
        if res.status_code < 429 or (res.status_code != 429 and res.status_code < 500):
            return res
        time.sleep(2 ** attempt)
    raise RuntimeError("max retries exceeded")
```