API 使用指南
错误码与限制
错误响应格式、常见错误码的原因和处理方法，以及请求限制。
错误格式
Chat Completions、Responses、Images、Embeddings 和其他 OpenAI 兼容端点使用这个格式：
{
"error": {
"message": "Model not found: no-such-model",
"type": "invalid_request_error",
"param": null,
"code": "model_not_found"
}
}所有上游都失败时，错误中还可能有 upstream_status、upstream_code、upstream_type。它们来自最后一次失败的上游。code 可能直接使用上游的错误码，例如 context_length_exceeded。网关在返回前会删除上游错误中的敏感信息。
Messages 端点使用 Anthropic 的格式，没有 code 字段：
{
"type": "error",
"error": { "type": "invalid_request_error", "message": "Model not found: no-such-model" },
"request_id": "3c3d7689-2f68-4659-af78-0dfe05be37b3"
}流式请求中，部分错误以流事件的形式出现，HTTP 状态码为 200。见流式输出。
每个响应都带有 x-request-id 响应头。报告问题时请提供它。
错误码
认证和账户
| HTTP | code | 原因 | 处理 |
|---|---|---|---|
| 401 | unauthorized | 缺少密钥、密钥无效、已禁用或已过期，或密钥没有可用的分组。 | 检查请求头和密钥状态。Authorization 必须以 Bearer 开头。 |
| 403 | email_unverified | 账户邮箱未验证。 | 登录控制台验证邮箱。 |
| 403 | ip_not_allowed | 请求 IP 不在密钥的 IP 白名单中。 | 修改密钥的 IP 白名单。 |
| 403 | device_ip_limit_reached | LynShen Desktop 设备密钥的 IP 数量超过上限。普通 API 密钥不受这个限制。 | 在授权设备页面查看 IP，或购买额外的 IP 坐席。 |
| 403 | model_not_allowed | 密钥开启了模型限制，请求的模型不在列表中。 | 修改密钥的模型限制。 |
余额和额度
| HTTP | code | 原因 | 处理 |
|---|---|---|---|
| 402 | insufficient_balance | 账户或子账户余额不足。 | 充值。 |
| 402 | api_key_spend_limit_reached | 密钥的总额、每小时或每日消费限额已用完。 | 等待窗口重置，或提高限额。 |
| 402 | org_spend_limit_reached | 组织空间的消费限额已用完。 | 联系组织管理员。 |
| 402 | plan_quota_exhausted | 套餐额度已用完。 | 等待额度重置，或改用余额。 |
| 423 | plan_payment_hold | 套餐因付款问题被暂停。 | 联系客服。 |
请求和模型
| HTTP | code | 原因 | 处理 |
|---|---|---|---|
| 400 | invalid_request | 请求不符合要求，例如 n 大于 1、Claude 推理时 temperature 不为 1、budget_tokens 不小于 max_tokens。 | 按 message 修改请求。 |
| 400 | previous_response_not_found | previous_response_id 指向的历史不存在或已过期。 | 改为发送完整历史。 |
| 403 | content_blocked | 请求内容命中了网关的内容防火墙规则。type 为 content_policy_violation。 | 修改请求内容。 |
| 403 | model_pricing_required | 这个模型还没有配置价格，暂时不能调用。 | 换一个模型，或联系客服。 |
| 404 | model_not_found | 你的账户类别中没有这个模型。 | 用 /v1/models 查询正确的模型 ID。 |
| 413 | 请求体超过 50 MiB。 | 压缩图片或减少上下文。 |
上游和网关
| HTTP | code | 原因 | 处理 |
|---|---|---|---|
| 429 | rate_limit_exceeded | 所有尝试的上游都返回了限流。 | 等待几秒后重试。 |
| 502 | upstream_error 或上游错误码 | 所有尝试的上游都失败了。 | 查看 message 和 upstream_status。可重试的错误稍后重试。 |
| 502 | unsupported_output_media | 模型返回了当前协议无法表示的内容，例如 Chat 中的图片。 | 换用 Responses 或 Images 端点。 |
| 502 | upstream_stream_incomplete | 上游的流在完成前中断。 | 重试。 |
| 503 | no_healthy_upstream | 模型存在，但当前没有可用的上游。设置的倍率上限过低也会导致这个错误。 | 稍后重试，或换一个模型。 |
| 503 | gateway_saturated | 网关当前并发已满。响应带有 Retry-After: 2。 | 2 秒后重试。 |
| 504 | upstream_idle_timeout | 上游长时间没有返回数据。 | 重试。长任务请使用流式输出。 |
重试建议
- 可以重试：
429、502、503、504。使用指数退避，例如 1 秒、2 秒、4 秒，最多 3 到 5 次。 - 不要重试：
400、401、402、403、404。先修改请求或账户设置。 - 网关已经在内部对可重试的失败切换上游。客户端收到
5xx时，说明所有候选上游都失败了。 - 流式响应开始后，网关不会切换上游。客户端需要重新发送整个请求。
请求限制
| 项目 | 限制 |
|---|---|
| 请求体大小 | 50 MiB |
Chat Completions 的 n | 只能为 1 |
| 图片编辑的源图片数 | 1 到 16 张，蒙版最多 1 张 |
图片流式输出的 n | 只能为 1 |
| 视频请求体 | 1 MiB |
| Responses WebSocket | 每个连接默认最多 128 轮，单条消息最大 50 MiB |
previous_response_id 历史 | 30 分钟后失效，进程重启时清除 |
| LynShen Desktop 设备密钥 | 每个账户 5 台设备、5 个活跃 IP（可购买额外坐席） |
普通 API 密钥没有固定的每分钟请求数限制。上游限流和网关并发上限仍然适用。