错误码

所有错误返回 JSON，error 对象含 type、message，有时带 code（code 目前存在时只是把 type 原样复制一份，做分支判断请用 type）。

没有 error.param 字段——跟其他一些厂商的 API 不同，ModelSite 的错误对象不会单独标出是哪个参数出的错，出错细节看 error.message。

状态码

状态码	真实 `type` 值	含义	排查
`400`	`invalid_request_error`	请求格式/参数错误，或 `model` 未知	检查 body、必填字段、`model`
`401`	`authentication_error`	API Key 缺失、无效或已过期	确认 `Authorization: Bearer` 头，以及控制台里 Key 的有效期
`402`	`insufficient_quota`	余额不足	充值
`403`	`model_access_error`（Key 无权用该模型）/ `permission_denied_error`（上游拒绝）	无权访问该模型/操作	确认 Key 权限或模型开放范围
`404`	`not_found_error`	查询的资源不存在（单个模型、`response_id`、`cache_id`）	核对 ID——模型用 `GET /v1/models`
`408`	`timeout_error`	上游调用超时	重试
`413`	`invalid_request_error`	请求体过大	减少 token
`422`	`unprocessable_entity_error`	请求格式合法但语义无法处理	检查 `tools`/`response_format` 等
`429`	`rate_limit_error`	触发限流	降并发，按 `Retry-After` 退避
`500`	`server_error` / `internal_server_error`	平台内部异常	通常是临时性的；持续报错请联系支持
`502`	`server_error` / `bad_gateway_error`	上游不可达	平台自动切换上游；稍后重试
`503`	`overloaded_error`	平台达到容量上限，或所有上游都已耗尽	退避后重试，看 `Retry-After`

500/502 具体会拿到上表两个 type 值中的哪一个，取决于内部哪个环节失败——请按状态码分支处理，不要依赖具体是哪个字符串。

上表是平台归一化后的 type 集合——极少数情况下你也可能看到 content_policy_violation 或 context_length_exceeded（都是 400）作为最终错误冒出来。

错误响应

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: foo-1"
  }
}

字段	说明
`error.type`	错误类别（见上表）——做分支判断用这个字段
`error.message`	人可读的说明
`error.code`	有时会出现；目前只是 `error.type` 的复制品，不是更细粒度的错误码

重试策略

在你收到任何响应内容之前发生的 5xx / 上游超时，平台已经自动重试过了，这种情况不需要客户端激进重试。客户端应该对 429 和 503（都带 Retry-After）做指数退避，并为极少数"流已经开始后中途中断"的场景自建重试——这种情况是终态，已经流出的部分仍会计费。

import time
def call_with_retry(fn, tries=4):
    for i in range(tries):
        try:
            return fn()
        except RateLimitError:
            time.sleep(2 ** i)   # 1, 2, 4, 8s
    raise

状态码

错误响应

重试策略

On this page