错误处理 — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# 错误处理

SupaNexus API（`/v1/*`）错误响应采用 **[OpenRouter 兼容格式](https://openrouter.ai/docs/api/reference/errors-and-debugging)**：`error.code` 为 **数字**，与 HTTP 状态码一致。

## 错误 JSON 格式

```json
{
  "error": {
    "code": 402,
    "message": "Your account or API key has insufficient credits. Add more credits and retry the request.",
    "metadata": {}
  }
}
```

| 字段 | 说明 |
|------|------|
| `error.code` | **整数**，等于 HTTP 响应 status |
| `error.message` | 人类可读描述 |
| `error.metadata` | 可选扩展（如 provider 错误详情） |

## HTTP 状态码参考

| HTTP | 场景 |
|------|------|
| 400 | 参数无效、JSON 解析失败；`video_url` 非公网 http(s)（含 data URI / file / 厂商私有 scheme） |
| 401 | API Key 缺失、错误或过期 |
| 413 | 请求体超过上限（默认 **64 MB**，`error.code` = `request_too_large`） |
| 402 | 账户/API Key 余额不足 |
| 403 | 账号已封禁，或权限不足 / 缺少组织/项目上下文 |
| 404 | 模型不存在或不可售卖 |
| 408 | 请求超时 |
| 409 | 幂等 Key 重复使用 |
| 429 | 速率或用量配额超限（可能有 `Retry-After`） |
| 501 | Embeddings / Images 尚未实现 |
| 502 | 服务暂时不可用 |
| 503 | 服务暂时不可用 |
| 500 | 服务内部错误 |

## 账号封禁（403）

平台用户被管理员封禁后，所有 `/v1/*` 请求在 API Key 校验通过后返回：

```json
{
  "error": {
    "code": 403,
    "message": "Your account has been suspended. Contact support for assistance."
  }
}
```

- 与 Key 是否有效无关（Key 未销毁时仍可能返回此错误）
- 解封后立即恢复，无需重新创建 Key
- 详见 [认证 — 账号封禁校验](./authentication.md#账号封禁校验)

## 重试建议

| HTTP | 是否重试 | 说明 |
|------|----------|------|
| 401 | 否 | 修正 API Key |
| 403 | 否 | 账号封禁时联系管理员；其它 403 检查权限与上下文 |
| 402 | 否 | 充值或联系平台管理员 |
| 404 | 否 | 使用有效 model id |
| 408 | 视情况 | 缩短 payload 或增加客户端超时 |
| 409 | 否 | 使用新的 Idempotency-Key |
| 429 | 是 | 遵守 `Retry-After` |
| 502 | 视情况 | 指数退避后重试 |
| 503 | 视情况 | 短间隔退避 |

## 服务认证失败

推理服务认证失败时，SupaNexus 通常返回 **502**，消息为 `"Upstream authentication failed."`，不暴露服务商细节。

## Anthropic `/v1/messages` 错误

`POST /v1/messages` 返回 **Anthropic 形态** JSON，而非 OpenRouter 数字 code：

```json
{
  "type": "error",
  "error": {"type": "authentication_error", "message": "Invalid API key"}
}
```

详见 [Messages](./messages.md)。Chat Completions 仍使用上文 OpenRouter 格式。

## 流式错误

**流开始前**的错误使用上述 JSON 格式与对应 HTTP 状态码。见 [流式响应](./streaming.md)。

## 相关

- [限流与配额](./rate-limits-and-quotas.md)
- [认证](./authentication.md)