错误与排查

理解 API 错误并处理 Playground 常见问题。

状态码	含义	处理方式
`400`	月份范围反向（`INVALID_MONTH_RANGE`）或超过 24 个月（`MONTH_RANGE_TOO_LARGE`）。	修正销售月份范围；更长导出请拆为每次最多 24 个月。
`401`	Bearer 请求头缺失、格式错误或 Key 无效。	检查请求头和当前 Key。
`422`	日期或 `segment` 缺失或格式无效。	使用 ISO 日期以及 `normal`、`sample` 或 `all`。
`429`	共享 Key 在 60 秒内超过 30 次请求（`RATE_LIMIT_EXCEEDED`）。	等待响应头 `Retry-After` 指定的秒数后再重试。
`503`	服务端没有配置外部 API Key。	联系 Mellow；更换调用 Key 无法解决。
`504`	数据库查询超过 30 秒（`QUERY_TIMEOUT`）。	稍后重试或缩短销售月份范围；持续出现时联系 Mellow。

限流重试

v1 Key 的进程内全局限额是每 60 秒 30 次已认证请求。无效 Key 返回 401，不占用这份配额。收到 429 后请遵循 Retry-After；窗口重置前立即重试仍会失败。

实时 Playground 只允许从 https://docs.mellow.billgateai.com 发起请求。从其他网站或本地 HTML 页面复制发起的请求会被浏览器主动阻止。此时请使用 curl 或服务端 HTTP 客户端。

这不是网络错误，而是表示按产品利润页面相同的覆盖规则，该项成本暂不可用。详见成本口径。