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

# HHAPI 错误响应说明：HTTP 状态码 400–503 含义与 error 错误对象字段处理指南

> HHAPI 使用标准 HTTP 状态码标识错误类别，包括 400、401、403、404、429、500 和 503。错误响应体包含 error.message 可读说明、error.type 分类类型和 error.code 具体标识符，error.code 取值待确认，以实际 API 响应为准。

当 API 请求未能成功处理时，HHAPI 会返回一个非 2xx 的 HTTP 状态码，同时在响应体中包含结构化的 `error` 对象，详细描述错误类型和原因。开发者应优先读取 `error.message` 字段获取人类可读的错误说明，并结合 HTTP 状态码和 `error.code` 字段进行程序化错误处理与重试判断。

## 错误响应格式

所有错误响应体的 JSON 结构如下：

```json theme={null}
{
  "error": {
    "message": "错误描述信息",
    "type": "error_type",
    "code": "error_code"
  }
}
```

## 错误字段说明

<ResponseField name="error.message" type="string">
  人类可读的错误描述，说明请求失败的具体原因。建议在日志和用户提示中展示此字段内容。
</ResponseField>

<ResponseField name="error.type" type="string">
  错误的分类类型，如 `"authentication_error"`、`"invalid_request_error"`、`"rate_limit_error"` 等，可用于程序化分类处理。
</ResponseField>

<ResponseField name="error.code" type="string">
  具体的错误代码标识符，粒度比 `type` 更细。**注意：具体 code 取值待确认，以实际 API 返回为准。**
</ResponseField>

## HTTP 状态码说明

| 状态码 | 含义 | 常见原因 | 建议操作 |
| - | - | - | - |
| `400` | 请求参数错误 | 参数缺失、类型不正确或格式非法 | 检查请求体，参照接口文档修正参数 |
| `401` | 未授权 | API Key 缺失、格式错误或已失效 | 检查 `Authorization` 头，确认密钥有效 |
| `403` | 禁止访问 | API Key 有效，但无权限访问该资源或功能 | 确认账户权限，如有需要请联系支持 |
| `404` | 未找到 | 接口路径拼写错误或使用了不存在的端点 | 检查 Base URL 和路径是否正确 |
| `429` | 超出速率限制 | 短时间内请求过于频繁，超出频率配额 | 降低请求频率，实现指数退避重试策略 |
| `500` | 服务端内部错误 | HHAPI 服务端发生未预期的异常 | 稍后重试；若持续出现请联系技术支持 |
| `503` | 服务不可用 | 服务临时维护或过载 | 稍后重试，关注服务状态公告 |

## 常见错误码对照

以下为部分常见错误场景对应的 `error.code` 参考值。**注意：具体 code 字符串待确认，以实际 API 响应为准，此处保留结构框架供参考。**

| error.code（待确认） | 对应状态码 | 说明 |
| - | - | - |
| `invalid_api_key` | `401` | API Key 无效或格式错误 |
| `api_key_missing` | `401` | 请求未携带 API Key |
| `insufficient_quota` | `403` | 账户余额不足或配额已用尽 |
| `model_not_found` | `404` | 指定的模型 ID 不存在 |
| `rate_limit_exceeded` | `429` | 超出请求速率限制 |
| `context_length_exceeded` | `400` | 输入内容超出模型最大上下文长度 |

## 错误处理示例

以下示例均从环境变量读取 API Key 和 Base URL，避免硬编码敏感信息。

<AccordionGroup>
  <Accordion title="Python 错误处理示例">
    ```python theme={null}
    import os
    import openai

    client = openai.OpenAI(
        api_key=os.environ["HHAPI_API_KEY"],
        base_url=os.environ["API_BASE_URL"] + "/v1",
    )

    try:
        response = client.chat.completions.create(
            model="<MODEL_ID>",
            messages=[{"role": "user", "content": "你好"}],
        )
        print(response.choices[0].message.content)

    except openai.AuthenticationError as e:
        # 401 / 403：鉴权失败
        print(f"鉴权错误：{e.message}")

    except openai.RateLimitError as e:
        # 429：超出速率限制，建议退避重试
        print(f"速率限制：{e.message}，请稍后重试")

    except openai.BadRequestError as e:
        # 400：请求参数错误
        print(f"请求参数错误：{e.message}")

    except openai.APIStatusError as e:
        # 其他非 2xx 错误
        print(f"API 错误 {e.status_code}：{e.message}")
    ```
  </Accordion>

  <Accordion title="Node.js 错误处理示例">
    ```javascript theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
      apiKey: process.env.HHAPI_API_KEY,
      baseURL: process.env.API_BASE_URL + "/v1",
    });

    async function main() {
      try {
        const response = await client.chat.completions.create({
          model: "<MODEL_ID>",
          messages: [{ role: "user", content: "你好" }],
        });
        console.log(response.choices[0].message.content);

      } catch (error) {
        if (error instanceof OpenAI.AuthenticationError) {
          // 401 / 403：鉴权失败
          console.error("鉴权错误：", error.message);

        } else if (error instanceof OpenAI.RateLimitError) {
          // 429：超出速率限制
          console.error("速率限制，请稍后重试：", error.message);

        } else if (error instanceof OpenAI.BadRequestError) {
          // 400：请求参数错误
          console.error("请求参数错误：", error.message);

        } else if (error instanceof OpenAI.APIError) {
          // 其他 API 错误
          console.error(`API 错误 ${error.status}：`, error.message);

        } else {
          throw error;
        }
      }
    }

    main();
    ```
  </Accordion>
</AccordionGroup>

<Note>
  如果您频繁遇到鉴权相关错误（`401`/`403`），请参阅 [鉴权常见问题](/faq/auth-errors) 排查密钥配置问题。
</Note>