错误码

kukuai.fyi 把上游 provider 的错误统一映射为稳定的 HTTP 状态与业务 code，方便客户端做统一处理。

所有错误响应都遵循以下统一结构（与 OpenAI 协议保持兼容）：

error envelopejson

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for model deepseek-v4-pro",
    "param": null,
    "request_id": "req_01HZX3..."
  }
}

HTTP 状态对照

4xx 客户端错误

HTTP

code

含义

建议处理

400

invalid_request_error

type: invalid_request_error

请求体不合法，例如缺少字段或字段类型错误。

修复请求结构后重试，不要无脑重试。

400

context_length_exceeded

type: invalid_request_error

输入 token 超过模型 context_window 上限。

裁剪历史消息或换用 context 更大的模型；可以先调用 /v1/models 查 context_window。

400

invalid_model

type: invalid_request_error

model 字段非法或当前账号不可用。

调用 /v1/models 列出可用模型并刷新本地缓存。

401

invalid_api_key

type: authentication_error

API Key 缺失、格式错误或已撤销。

检查环境变量与 Header；必要时在控制台重新生成。

403

permission_denied

type: permission_error

当前 Key 没有调用该模型 / 该端点的权限。

在控制台为对应 Key 开通模型权限，或换一把更高权限的 Key。

404

model_not_found

type: invalid_request_error

模型 ID 不存在或已下架。

回退到列表中的等价模型；同时刷新 /v1/models 缓存。

408

request_timeout

type: timeout_error

上游模型在网关侧设定的超时窗口内未返回。

建议带退避的重试；流式请求可在客户端做断点续读。

409

conflict

type: invalid_request_error

资源状态冲突，例如重复的 idempotency key。

更换 idempotency key 或确认上一次请求的最终状态后再处理。

413

payload_too_large

type: invalid_request_error

请求体超过网关上限（含 base64 多模态内容）。

压缩或分片上传；图片/音频走对应的多模态接口。

422

unprocessable_entity

type: invalid_request_error

语义合法但模型无法处理（例如违反 response_format 约束）。

检查 response_format / tools 定义。

429

rate_limit_exceeded

type: rate_limit_error

触发账号 / Key / 模型级限速。

退避重试；尊重 Retry-After Header。具体上限以控制台显示为准。

429

insufficient_quota

type: rate_limit_error

账户余额或额度不足。

在控制台充值或申请额度，不要重试。

400invalid_request_error
请求体不合法，例如缺少字段或字段类型错误。
建议：修复请求结构后重试，不要无脑重试。
400context_length_exceeded
输入 token 超过模型 context_window 上限。
建议：裁剪历史消息或换用 context 更大的模型；可以先调用 /v1/models 查 context_window。
400invalid_model
model 字段非法或当前账号不可用。
建议：调用 /v1/models 列出可用模型并刷新本地缓存。
401invalid_api_key
API Key 缺失、格式错误或已撤销。
建议：检查环境变量与 Header；必要时在控制台重新生成。
403permission_denied
当前 Key 没有调用该模型 / 该端点的权限。
建议：在控制台为对应 Key 开通模型权限，或换一把更高权限的 Key。
404model_not_found
模型 ID 不存在或已下架。
建议：回退到列表中的等价模型；同时刷新 /v1/models 缓存。
408request_timeout
上游模型在网关侧设定的超时窗口内未返回。
建议：建议带退避的重试；流式请求可在客户端做断点续读。
409conflict
资源状态冲突，例如重复的 idempotency key。
建议：更换 idempotency key 或确认上一次请求的最终状态后再处理。
413payload_too_large
请求体超过网关上限（含 base64 多模态内容）。
建议：压缩或分片上传；图片/音频走对应的多模态接口。
422unprocessable_entity
语义合法但模型无法处理（例如违反 response_format 约束）。
建议：检查 response_format / tools 定义。
429rate_limit_exceeded
触发账号 / Key / 模型级限速。
建议：退避重试；尊重 Retry-After Header。具体上限以控制台显示为准。
429insufficient_quota
账户余额或额度不足。
建议：在控制台充值或申请额度，不要重试。

5xx 服务端错误

HTTP

code

含义

建议处理

500

internal_error

type: api_error

网关或上游内部错误。

指数退避重试，超过 3 次仍失败建议人工排查并提供 request id。

502

upstream_error

type: api_error

上游 provider 返回非预期错误。

可重试；如果稳定复现，换备用模型或联系支持。

503

service_unavailable

type: api_error

上游容量受限，常见于热门模型瞬时拥塞。

退避重试；启用智能路由的账号一般会自动切换备用 provider。

504

gateway_timeout

type: api_error

网关到上游超时。

同 408；如果是流式请求注意检查 last-event-id。

500internal_error
网关或上游内部错误。
建议：指数退避重试，超过 3 次仍失败建议人工排查并提供 request id。
502upstream_error
上游 provider 返回非预期错误。
建议：可重试；如果稳定复现，换备用模型或联系支持。
503service_unavailable
上游容量受限，常见于热门模型瞬时拥塞。
建议：退避重试；启用智能路由的账号一般会自动切换备用 provider。
504gateway_timeout
网关到上游超时。
建议：同 408；如果是流式请求注意检查 last-event-id。

重试策略

立即失败：4xx 中除429 / 408 外，多数无需重试。
指数退避：429 / 5xx 推荐 base = 500ms 起，乘 2，最大 8s，并尊重响应 HeaderRetry-After。
幂等性：可选发送Idempotency-Key Header（UUID v4），重试时复用同一个 key，网关会避免重复扣费。
退路模型：在客户端定义一个备选模型列表，遇到 model_not_found / service_unavailable 时降级。

排障：使用 request_id

每次响应（成功或失败）都会带上 X-Request-Id Header，失败响应体也包含 error.request_id。提交工单或在 FAQ提到的任何排查流程中都需要这个 ID——它能让我们直接定位到具体一次请求的链路日志。

错误码 ​

HTTP 状态对照 ​

4xx 客户端错误 ​

5xx 服务端错误 ​

重试策略 ​

排障：使用 request_id ​

错误码

HTTP 状态对照

4xx 客户端错误

5xx 服务端错误

重试策略

排障：使用 request_id