API 参考

状态码与故障处理

先检查 HTTP 状态，再根据业务 code 定位原因。所有错误响应都应包含可用于排查的 requestId。

2xx

请求成功

可以继续处理业务数据

4xx

请求需修正

检查认证、参数与调用频率

5xx

服务暂不可用

有限重试并保留请求标识

HTTP	业务 code	名称	说明	建议操作
200	0	请求成功	请求已完成，业务数据位于 data 字段。	继续处理返回数据
400	40001	参数错误	缺少必填字段或字段类型不正确。	根据 details 修正参数
401	40101	认证失败	密钥缺失、无效或已经被吊销。	检查 Authorization 请求头
403	40301	权限不足	当前方案无权访问该接口或数据范围。	检查方案与接口权限
404	40401	资源不存在	路由、接口编号或目标资源不存在。	核对请求路径和标识
429	42901	请求过快	当前时间窗口的请求数已经超过限制。	读取 Retry-After 后重试
500	50001	服务异常	服务暂时无法完成请求。	有限重试并保留 requestId
503	50301	上游不可用	目标数据源临时维护或响应不稳定。	延迟重试或稍后查询

错误响应结构

{
  "code": 42901,
  "message": "rate limit exceeded",
  "details": { "retryAfter": 2 },
  "requestId": "req_local_8f2a"
}

故障处理顺序