> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误

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

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

```json theme={null}
{
  "type": "error",
  "request_id": "req_01...",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}
```

<ResponseField name="type" type="string">
  顶层对象类型。错误响应固定为 `error`。
</ResponseField>

<ResponseField name="request_id" type="string">
  本次请求的追踪 ID。联系部署运维人员时应一并提供。
</ResponseField>

<ResponseField name="error.type" type="string">
  稳定的错误分类，例如 `authentication_error`、`invalid_request_error` 或 `not_found_error`。
</ResponseField>

<ResponseField name="error.message" type="string">
  面向开发者的错误说明。不要依赖完整文案做程序分支判断。
</ResponseField>

## 常见状态码

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

## 重试

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

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