> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlight.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误

> 处理 OpenLight Public API 错误响应

OpenLight 会针对认证、授权、参数校验、资源不存在、状态冲突、限流和服务器故障返回结构化 JSON 错误。

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required.",
    "request_id": "req_01HR8Y4Q9M5K2X7J3A6B8C9D0E"
  }
}
```

常见错误码：

* `unauthorized`：请求缺少有效 API Token。
* `forbidden`：Token 没有访问该资源的权限。
* `not_found`：资源不存在，或对 Token 所有者不可见。
* `validation_error`：请求体或查询参数无效。
* `conflict`：请求与当前资源状态冲突。
* `rate_limited`：短时间内发送了过多请求。
* `internal_error`：API 无法完成请求。

请使用 HTTP 状态码做流程控制，使用错误码做产品侧处理。联系 OpenLight 支持时，请附上 `request_id`。