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

# 错误处理

> 解析 Yelu AI API 错误、理解 HTTP 状态码并实现安全重试与可观测性。

Yelu 使用标准 HTTP 状态码和兼容 OpenAI 的 JSON 错误结构。

## 错误结构

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "message": "The requested model is not available for this key.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

<ResponseField name="error" type="object" required>
  顶层错误对象。

  <Expandable title="字段">
    <ResponseField name="message" type="string" required>便于阅读的诊断信息，不要依赖它编写分支逻辑。</ResponseField>
    <ResponseField name="type" type="string">错误类别，例如 `invalid_request_error`。</ResponseField>
    <ResponseField name="param" type="string | null">与错误相关的请求字段。</ResponseField>
    <ResponseField name="code" type="string | null">可用时返回的机器可读错误码。</ResponseField>
  </Expandable>
</ResponseField>

## HTTP 状态码

| 状态码         | 含义                | 建议                  |
| ----------- | ----------------- | ------------------- |
| `400`       | JSON、字段、参数或模型能力无效 | 修正请求，不要原样重试         |
| `401`       | API Key 缺失或无效     | 检查 Bearer 鉴权或轮换 Key |
| `403`       | Key 或账号无权执行操作     | 检查权限和模型访问范围         |
| `404`       | 端点或模型不存在          | 检查路径并刷新模型列表         |
| `413`       | 请求或文件过大           | 缩小内容或文件             |
| `429`       | 达到请求限制            | 使用抖动退避并降低并发         |
| `500`–`504` | 网关或上游暂时失败         | 在有限预算内退避重试          |

## 统一错误处理

<CodeGroup>
  ```bash Curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  status=$(curl -sS -o response.json -w "%{http_code}" \
    https://api.yelu.ai/v1/models \
    -H "Authorization: Bearer $YELU_API_KEY")
  [ "$status" -ge 400 ] && jq '.error' response.json >&2 && exit 1
  jq . response.json
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  async function yelu(path, options = {}) {
    const response = await fetch(`https://api.yelu.ai/v1${path}`, {
      ...options,
      headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}`, 'Content-Type': 'application/json', ...options.headers },
    });
    const body = await response.json().catch(() => null);
    if (!response.ok) {
      const error = new Error(body?.error?.message ?? `HTTP ${response.status}`);
      error.status = response.status;
      error.code = body?.error?.code;
      throw error;
    }
    return body;
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  def yelu(method, path, **kwargs):
      response = requests.request(
          method,
          f"https://api.yelu.ai/v1{path}",
          headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
          timeout=60,
          **kwargs,
      )
      response.raise_for_status()
      return response.json()
  ```
</CodeGroup>

日志应记录状态码、错误 `type`/`code`、端点、模型、重试次数和延迟，同时脱敏 Authorization、Prompt、工具参数、文件和用户数据。