错误码

MCP 和 HTTP API 共享一套错误响应结构。本页汇总所有业务错误码与排查建议。

响应结构

所有非二进制响应统一格式：

{
  "code": "0000",
  "msg": "ok",
  "data": { /* 成功时返回 */ },
  "metadata": { /* 计费与配额信息 */ }
}

• code："0000" 为成功，其他均表示异常
• msg：简短的成功/失败信息
• data：成功时返回业务数据；失败时为 null
• metadata：计费与配额信息（仅成功时出现，详见 使用统计）
• errorId：错误代码，仅失败时出现，如无法排查，可联系技术支持

失败响应示例：

{
  "code": "QUOTA_DAY",
  "msg": "今日额度已用尽，请等待明日重置或升级套餐",
  "data": null,
  "errorId": "b3f2a4ad-..."
}

HTTP 状态码总览

HTTP	含义
200	成功
400	参数错误（缺字段、类型不对、枚举越界、多 Key 冲突）
401	鉴权失败（未带 Key、格式非法）
403	Key 被吊销 / 用户停用
429	触发额度或限速
500	服务端内部异常
502	Keepa 上游异常

错误码

鉴权类（4xx）

code	HTTP	含义	排查方向
4001	401	缺少 API Key	检查请求头 X-API-Key / Authorization: Bearer / URL ?key= 三者之一是否带上
4001	401	API Key 格式错误	应为 km_ + 32 位字符，总长 35
4001	400	多个位置传入了不同的 Key	只保留一处；推荐 X-API-Key
4003	403	Key 无效、已吊销或用户不可用	Key 是否已被重置？账号是否正常？

参数类（4xx）

code	HTTP	含义	排查方向
4000	400	参数校验失败	查看 msg 字段，按提示修正

配额类（429）

code	HTTP	含义	排查方向
QUOTA_MINUTE	429	每分钟限速触顶	退避重试，建议指数退避起始 1s
QUOTA_DAY	429	当日额度用尽	等待次日重置或升级套餐
QUOTA_MONTH	429	当月额度用尽	等待下周期或升级套餐
QUOTA_OFF_PEAK_WINDOW	429	仅闲时套餐且当前非闲时窗口	等待 19:00 或加购通用套餐
QUOTA_NO_SUBSCRIPTION	429	账号未购买任何套餐	购买套餐
QUOTA_EXCEEDED	429	综合额度耗尽	见 msg 详情

执行类（5xx）

code	HTTP	含义	排查方向
EXECUTION_ERROR	500	服务端内部异常	记录 errorId，联系技术支持
EXECUTION_ERROR	502	从keepa获取数据失败	同上；可稍后重试
5000	500	查询额度失败（/api/token ）	稍后重试

执行类错误不会消耗套餐额度。

批量部分失败

keepa_get_product 批量查询中，部分 ASIN 失败不会使整个请求失败——成功的在 products 里，失败的在 errors 列表里，每条带各自的 errorId，可按需单独重试。

排查流程

1. 先看 code：锁定错误大类
2. 读 msg：多数情况有明确提示
3. 配额类：检查响应 metadata.quotaHint（成功响应里一直有），按剩余量规划调用节奏
4. 执行类：务必保存 errorId，这是定位问题唯一的钥匙
5. 批量部分失败：data.errors 列表里每条都有自己的 errorId，按需单独重试

quotaHint 字段

每次成功响应都带 metadata.quotaHint，反映扣费之后的套餐余量：

字段	含义
minute.limit / minute.remaining	每分钟限额与剩余
day.limit / day.remaining	今日限额与剩余
month.limit / month.remaining	本月限额与剩余

客户端应优先读 quotaHint 做自适应限速，效果与调用 keepa_get_quota 一致但零额外请求。

重试策略

错误	重试？	策略
4000 / 4001 / 4003	不重试	检查key、参数错误
QUOTA_MINUTE	重试	指数退避 1s → 30s
QUOTA_DAY / QUOTA_MONTH	不重试	等待周期重置或升级套餐
QUOTA_OFF_PEAK_WINDOW	视情况	等到闲时窗口或加购通用套餐
EXECUTION_ERROR (502)	重试	退避重试 2–3 次；仍失败联系支持
EXECUTION_ERROR (500)	谨慎	优先联系支持，带上 errorId