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

错误响应格式

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

错误字段说明

string
人类可读的错误描述,说明请求失败的具体原因。建议在日志和用户提示中展示此字段内容。
string
错误的分类类型,如 "authentication_error"、"invalid_request_error"、"rate_limit_error" 等,可用于程序化分类处理。
string
具体的错误代码标识符,粒度比 type 更细。注意:具体 code 取值待确认,以实际 API 返回为准。

HTTP 状态码说明

常见错误码对照

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

错误处理示例

以下示例均从环境变量读取 API Key 和 Base URL,避免硬编码敏感信息。
如果您频繁遇到鉴权相关错误(401/403),请参阅 鉴权常见问题 排查密钥配置问题。