稀疏空间地图 APIs 错误码说明
响应格式
所有 API 响应均采用统一的 JSON 格式，以下是一个示例 :
{
"statusCode": 119,
"msg": "Parameter has errors",
"date": "2022-06-15T09:56:30.000Z",
"result": //statusCode 为 0 的情况才有 result，如果发生错误，结果字段为空
}
| 字段 | 类型 | 说明 |
|---|---|---|
| statusCode | integer | 业务状态码，0 表示成功，非 0 表示错误 |
| msg | string | 消息 |
| result | object | 返回内容，状态码是 0 时响应目标图对象结构，否则为空 |
| date | string | 服务器时间 |
重要事项
statusCode == 0 的条件下，result 才包括响应内容，其它状态下 result 为空
statusCode != 0 的条件下，请关注错误消息 msg
错误码分类
HTTP 状态码说明
| HTTP 状态码 | 说明 |
|---|---|
| 200 | 请求成功（可能包含业务错误） |
| 400 | 请求参数错误 |
| 401 | APIKey 认证失败 |
| 403 | 权限不足或资源禁止访问 |
| 404 | 请求 URL 接口 Path 不存在 |
| 500 | 服务器内部错误 |
| 502 | 应用异常捕获，可能数据错误 |
注意：业务错误通常通过 HTTP 200 响应返回，在 statusCode 字段中标识具体错误类型。
业务状态码一览表
| Status Code | Message |
|---|---|
| 0 | Success |
| 101 | Uploaded file is empty |
| 102 | File size is too large |
| 106 | Missing parameter or parameter is empty |
| 110 | Call server API errors |
| 111 | Resource not found |
| 401 | Authentication token expired |
| 401 | Authentication parameter is missing |
| 401 | Unknown appId or appKey |
| 401 | Account is locked |
| 401 | Authentication failed, invalid signature or token |
常见错误场景
超时无响应
- Request Timeout：网络比较慢，建议检查客户端的网络环境
认证相关错误
- Http 401 Unauthorized：APIKey 认证失败，检查 appId/appKey 是否正确
- 状态码 401：应用密钥无效或应用不存在，检查应用配置
参数错误
- 400 Bad Request：请求参数格式错误
资源操作错误
- 状态码 10x：查询的目标资源不存在，或者参数错误
系统错误
- Http 50x Internal Server Error：服务器内部异常或者应用异常捕获，建议在网站上测试或者 sample 测试
最佳实践建议
- 客户端处理：建议根据
statusCode字段判断业务是否成功，而非仅依赖 HTTP 状态码 - 错误重试：对于 5xx 错误可适当重试，对于 4xx 错误需检查请求参数
- 日志记录：建议记录完整的错误响应，便于问题排查
- 超时处理：设置合理的请求超时时间，避免长时间等待