云识别 APIs 错误码说明
响应格式
所有 API 响应均采用统一的 JSON 格式，以下是一个示例 :
{
"statusCode": 422,
"reuslt": "The image or meta exceeds its maximum permitted size",
"timestamp": 1514736000000,
"appKey": "test_app_key"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| statusCode | integer | 业务状态码，0 表示成功，非 0 表示错误 |
| result | string | 返回内容，状态码是 0 时响应目标图对象结构，否则就返回错误消息 |
| timestamp | long | 服务器 Unix 格式时间戳（毫秒级） |
重要事项
statusCode == 0 的条件下，result 才包括响应内容，其它状态下 result 返回错误消息。
错误码分类
HTTP 状态码说明
| HTTP 状态码 | 说明 |
|---|---|
| 200 | 请求成功（可能包含业务错误） |
| 400 | 请求参数错误 |
| 401 | APIKey 认证失败 |
| 403 | 权限不足或资源禁止访问 |
| 404 | 请求 URL 接口 Path 不存在 |
| 500 | 服务器内部错误 |
| 501 | 应用异常捕获，可能数据错误 |
| 502 | 服务器不可用，联系客服 |
注意
业务错误通常通过 HTTP 200 响应返回，在 statusCode 字段中标识具体错误类型。
业务状态码一览表
| Status Code | Message |
|---|---|
| 0 | ok |
| 1 | invalid appId (appKey) |
| 2 | invalid signature |
| 3 | invalid date |
| 4 | appId (appKey) not exist |
| 6 | invalid token |
| 6 | invalid appkey token |
| 7 | non-sdk client for dau databases |
| 8 | Dau databases are not compatible with sense-4.6+ any more. |
| 404 | Target not found |
| 414 | Parameter required not exists or not correct |
| 422 | The image or meta exceeds its maximum permitted size |
| 417 | fail to add image |
| 419 | Cannot update target in database because similar target exists. |
| 420 | Target delete failed |
| 424 | Target enable error |
| 403 | Target already exists |
| 426 | Judge exceeds maxium candidates |
| 427 | Image not correct |
常见错误场景
超时无响应
- Request Timeout：网络比较慢，建议检查客户端的网络环境
认证相关错误
- Http 401 Unauthorized：APIKey 认证失败，检查 appId/appKey 是否正确
- 状态码 401：应用密钥无效或应用不存在，检查应用配置
参数错误
- 400 Bad Request：请求参数格式错误
- 状态码 414：必填参数缺失或参数值不符合要求
资源操作错误
- 状态码 404：查询的目标资源不存在
- 状态码 403：目标已存在，无法重复创建
- 状态码 417/420/424：增删改操作失败
文件相关错误
- 状态码 422：上传的文件大小超过限制
- 状态码 427：图片格式不支持或文件损坏
系统错误
- Http 500 Internal Server Error：服务器内部异常，建议在网站上测试或者 sample 测试
- Http 501 Exception：应用异常捕获，可能数据错误，建议在网站上测试或者 sample 测试
- Http 502 Server：服务响应错误，建议可能服务器错误，建议联系我们
最佳实践建议
- 客户端处理：建议根据
statusCode字段判断业务是否成功，而非仅依赖 HTTP 状态码 - 错误重试：对于 5xx 错误可适当重试，对于 4xx 错误需检查请求参数
- 日志记录：建议记录完整的错误响应，便于问题排查
- 超时处理：设置合理的请求超时时间，避免长时间等待