错误处理
本指南涵盖 k-ID API 的错误处理，包括常见错误代码、错误响应格式和处理错误的最佳实践。
错误响应格式
所有 API 错误都遵循一致的响应格式。错误响应包括 error 字段和 errorMessage 字段：
{
"error": "ERROR_CODE",
"errorMessage": "人类可读的错误消息"
}
HTTP 状态代码
k-ID API 使用标准 HTTP 状态代码来指示 API 请求的结果：
| 状态代码 | 说明 | 何时发生 |
|---|---|---|
| 200 | OK | 请求成功 |
| 400 | Bad Request | 无效的请求参数 |
| 401 | Unauthorized | 无效或缺少 API 密钥 |
| 429 | Too Many Requests | 超过速率限制 |
| 500 | Internal Server Error | 服务器错误 |
常见错误代码
身份验证错误
UNAUTHORIZED
状态： 401
说明： 无效或缺少 API 密钥
{
"error": "UNAUTHORIZED",
"errorMessage": "Unauthorized"
}
常见原因：
- 缺少 Authorization 标头
- 无效的 API 密钥格式
- 过期的 API 密钥
解决方法：
- 验证 API 密钥是否正确
- 检查密钥是否处于活动状态且未过期
- 确保密钥在 Authorization 标头中格式正确
请求验证错误
INVALID_INPUT
状态： 400
说明： 请求验证失败
{
"error": "INVALID_INPUT",
"errorMessage": "The age verification could not be found."
}
解决方法：
- 审查验证错误详细信息
- 更正无效的字段值
- 参考 API 文档了解有效值
资源错误
速率限制错误
状态： 429
说明： 超过速率限制
无响应正文
解决方法：
- 实施指数退避
- 降低请求频率
- 在适当时缓存响应
服务器错误
状态： 500
说明： 内部服务器错误
{
"error": "INTERNAL_ERROR",
"errorMessage": "Internal server error"
}
解决方法：
- 延迟后重试请求
- 如果错误持续存在，请联系支持
- 检查服务状态页面