深色模式
错误码
错误响应统一为 HTTP 状态码加一段 JSON：
json
{ "code": 404, "message": "资源 \"orders\" 不在开放白名单内" }code 与 HTTP 状态码一致。5xx 的错误信息会统一成通用文案，具体原因记在服务端日志里，需要时联系平台排查。
一览表
| HTTP | code | 含义 | 怎么处理 |
|---|---|---|---|
| 401 | missing_key | 请求头没带密钥 | 加上 X-API-Key |
| 401 | invalid_key | 密钥格式不对或不匹配 | 核对是否抄错、是否含多余空格 |
| 403 | key_disabled | Key 已停用 | 联系管理员启用或换新 Key |
| 403 | key_expired | Key 已过期 | 换新 Key |
| 403 | missing_scope | Key 没有只读查询能力域 | 让管理员在 Key 上开 open |
| 400 | bad_id | 路径里的 id 不是数字 | 传整数 id |
| 404 | resource_not_allowed | 资源名不在白名单 | 先调 meta 看可用资源名 |
| 404 | not_found | 记录不存在，或不在你的数据范围内 | 换 id 或确认数据归属 |
| 429 | quota_exceeded | 超出该 Key 的每分钟配额 | 退避后重试，或申请调整配额 |
| 503 | openapi_disabled | 平台关闭了开放接口 | 联系平台确认是否维护中 |
三类常见问题怎么定位
一直返回 401
九成是密钥抄错。检查顺序：请求头名字是否写成 X-API-Key、值是否完整（含 uak_ 前缀与两段下划线）、是否把「密钥摘要」当成了密钥本身。用 meta 试一下就能快速判断认证是否通过。
返回 404 说资源不存在
先调 meta，看返回的 resources 里有没有你要的资源名。资源名是固定的英文小写，不能自己拼。名字对、id 也对但仍 404，说明这条数据不在该 Key 的归属范围内。
偶尔 429
看调用频率是否在某个时间点集中。定时任务重跑、多个系统共用一个 Key、翻页过快都会造成瞬时高峰。把 page_size 调到 100、错开重跑时间、一个系统一个 Key，通常就能压下来。