错误码 - OpenPAI Docs

OpenPAI 在错误时返回标准 HTTP 状态码 + JSON 错误体。错误结构与 OpenAI 官方完全兼容,可以无缝接入现有 SDK 的错误处理。

错误响应结构

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

字段	含义
`message`	人类可读的错误描述,可直接展示给开发者
`type`	错误类别:`invalid_request_error` / `authentication_error` / `billing_error` / `rate_limit_error` / `server_error`
`param`	出错的字段名(若适用)
`code`	机器可识别的错误码

常见错误码

400 invalid_request

code	说明
`invalid_request_error`	请求体格式错误 / 缺少必填字段
`invalid_model`	模型 ID 不存在或不在令牌白名单
`context_length_exceeded`	输入 + 输出 token 超过模型上下文窗口
`unsupported_modality`	该模型不支持图片 / 音频 / 视频输入

401 authentication

code	说明
`invalid_api_key`	API Key 不存在 / 已删除 / 格式错误
`expired_api_key`	令牌已过期
`disabled_api_key`	令牌已被禁用

403 forbidden

code	说明
`insufficient_quota`	账户或令牌额度耗尽
`ip_not_allowed`	来源 IP 不在白名单
`model_not_allowed`	该令牌没有此模型权限

404 not_found

code	说明
`model_not_found`	模型不存在(已下线 / 拼写错误)
`resource_not_found`	资源(任务、文件)不存在

429 rate_limit

code	说明
`rate_limit_exceeded`	触发 RPM / TPM 限流
`concurrent_limit_exceeded`	并发数超过分组上限
`upstream_rate_limited`	上游厂商返回 429

429 响应头中包含 Retry-After(秒),建议使用指数退避重试。

5xx server_error

code	说明
`server_error`	网关内部错误,通常自动重试
`upstream_unavailable`	全部上游通道均不可用
`upstream_timeout`	上游超时
`bad_gateway`	上游返回非法响应

5xx 错误不会扣费(若上游已生成 token,会按实际用量结算)。

流式响应中的错误

流式响应中如果中途出错,会以 SSE 形式发送一个错误事件后关闭连接:

data: {"error":{"message":"Upstream timeout","type":"server_error","code":"upstream_timeout"}}

data: [DONE]

客户端应监听 SSE 数据中的 error 字段,而不仅是 HTTP 状态码。

重试建议

from openai import OpenAI
import time

client = OpenAI(api_key="sk-...", base_url="https://openp.ai/v1")

def call_with_retry(**kwargs):
    delay = 1
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.RateLimitError:
            time.sleep(delay)
            delay = min(delay * 2, 30)
        except openai.APIError as e:
            if e.status_code >= 500:
                time.sleep(delay)
                delay = min(delay * 2, 30)
            else:
                raise
    raise RuntimeError("max retries exceeded")

报告问题

收到无法理解的错误时:

复制响应头中的 X-OpenPAI-Request-Id。
在控制台 → 日志中搜索该 ID,查看模型、Token 用量、错误码等元数据。
仍不能定位,记录 Request ID 与复现步骤,等待后续问题排查。

​错误响应结构

​常见错误码

​400 invalid_request

​401 authentication

​403 forbidden

​404 not_found

​429 rate_limit

​5xx server_error

​流式响应中的错误

​重试建议

​报告问题