API 限制与错误代码

请求限额

两项限额都按整个账户计算：您所有的密钥和已连接的 AI 助手合并计算。

• 每分钟限额持续恢复：每秒恢复一次请求，最多恢复到 60 次。
• 每日限额是一个 24 小时的滚动窗口，不是自然日。X-RateLimit-Reset-Day 响应头会告诉您何时结束。

限流响应头

使用有效密钥的每个请求，返回结果中都带有：

达到限额时，返回 429 rate_limited，并附带 Retry-After 响应头：等待相应的秒数后再重新发送请求。

无论是否出错，每个返回结果都带有 X-Request-Id。

错误的格式

错误采用标准的“problem details”格式（application/problem+json）：

{
  "type": "https://gloriads.com/docs/api/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "limit must be between 1 and 100.",
  "issues": [
    {
      "path": "limit",
      "code": "invalid_value",
      "message": "limit must be between 1 and 100."
    }
  ],
  "request_id": "req_8fK2mQ7xLp3nR9sT1vWy"
}

• 在脚本中判断 code。 它永远不会变；detail 是写给人看的，措辞可能调整。
• issues 列出每个无效参数，只在 invalid_request 中出现。
• 联系客服时请提供 request_id。

错误代码

invalid_request · 400：某个参数无效，比如未知的值、超出范围的数字，或不是我们签发的分页游标。issues 会说明是哪个参数以及原因。

api_key_in_query · 400：密钥放在了 URL 中。请改为在 Authorization 请求头中发送，并吊销该密钥：它可能已经留在某个日志里了。

unauthorized · 401：没有密钥，或密钥错误、已吊销。返回结果特意不说明是哪一种。

subscription_inactive · 403：账户的订阅已结束。订阅恢复后，API 立即可以再次使用。

insufficient_scope · 403：该密钥没有读取权限。现在创建的每个密钥都能读取，所以您应该永远不会看到这个代码。

not_found · 404：该路径下没有端点，或您请求的内容在您的账户中不存在。属于其他账户的内容也会得到同样的结果。

method_not_allowed · 405：API 只接受 GET，因为它是只读的。Allow 响应头列出了它接受的方法。

amazon_not_connected · 409：/targets、/ads 和 /reports/streaming-tv 会在您请求时读取亚马逊，而亚马逊广告尚未连接，或需要重新连接。请在 Gloriads 的设置 → 亚马逊广告中处理。

rate_limited · 429：达到了限额。请等待 Retry-After 中的秒数。

internal_error · 500：我们这边出了问题。请稍后重试；如果问题持续，请把 request_id 发给我们。

amazon_unavailable · 502：亚马逊没有响应 /targets、/ads 或 /reports/streaming-tv，或无法生成流媒体电视广告报告。请几分钟后重试。

timeout · 504：响应时间超过了 30 秒。请减少每次请求的数据量。

返回值与分页

• null 表示“不存在”，绝不表示零。
• 长列表分页返回。 limit 设置每页条数：范围 1 到 100（默认 50）；广告活动和广告组最多 1,000（默认 100）。当 has_more 为 true 时，把 next_cursor 作为 cursor 发回，即可获取下一页。
• 一页的条数可能少于 limit，比如筛选后剩下的行很少时（某个广告活动的广告组）。请继续跟随 next_cursor，直到 has_more 为 false。