错误

理解 OMA 的 HTTP 状态码、错误信封和 request ID。

OMA 的公共 API 使用统一的兼容错误信封。

{
  "type": "error",
  "request_id": "req_01...",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}

type · string

顶层对象类型。错误响应固定为 error。

request_id · string

本次请求的追踪 ID。联系部署运维人员时应一并提供。

error.type · string

稳定的错误分类，例如 authentication_error、invalid_request_error 或 not_found_error。

error.message · string

面向开发者的错误说明。不要依赖完整文案做程序分支判断。

​

常见状态码

状态码	含义	建议
400	请求字段、分页或 beta 参数无效	修正请求后再试
401	缺少或无法识别凭证	检查 API 密钥和认证头
403	当前身份没有所需权限	检查工作区和资源权限
404	路由或租户范围内的资源不存在	检查路径与资源 ID
409	版本或资源状态冲突	重新读取资源后再提交
413	请求体或上传文件过大	缩小请求或检查部署限制
429	上游或部署限流	按 Retry-After 或指数退避重试
500	服务内部错误	使用 request_id 检查服务日志
502	上游模型或代理连接失败	检查上游状态并有限重试
503	所需上游配置或依赖不可用	修复部署配置后重试

​

重试

只对临时网络错误、429 或明确可恢复的 5xx 执行带抖动的指数退避。校验错误、认证错误和版本冲突需要先修改请求，盲目重试不会成功。

/v1/filestore 使用 rclone-filestore 协议需要的扁平错误格式，不使用本页的通用错误信封。