了解 API 请求与配额

你的订阅套餐包含每月请求额度。本页详细说明什么算作一次请求、哪些端点免费，以及达到限额时会发生什么。

什么是 1 次请求？

1 次请求 = 对一个计费 API 端点的 1 次调用，无论返回内容为何。

对计费端点的每次成功调用都会从你的配额中扣除恰好 1 次请求。响应大小、返回条目数量、查询参数或 HTTP 状态码对计数没有任何影响 —— 返回 1,000 条赛事的调用与返回 0 条赛事的调用都恰好消耗 1 次请求。

请求按订阅计数，因此使用你 API 密钥发起的所有调用都会累加到同一配额上。

哪些端点会被计数？

计费端点（计入你的配额）

对这些端点的每次调用都会消耗 1 次请求：

• /v4/players
• /v4/settlements
• /v4/fixtures
• /v4/fixture
• /v4/odds-by-tournaments
• /v4/languages
• /v4/sports
• /v4/bookmakers
• /v4/markets
• /v4/tournaments
• /v4/participants
• /v4/scores
• /v4/odds

免费端点（不计入你的配额）

• /v4/historical-odds —— 始终免费。调用永远不会增加你的请求计数。

不计量端点（不计入且永不被阻止）

• /v4/account —— 始终可用，即使配额已耗尽也能访问。这样你总能查询订阅状态和剩余配额。

请求何时被计数？

无论响应是否成功或返回错误，请求都会在端点完成处理之后被计数。包括：

• 200 OK — 成功的响应
• 4xx — 客户端错误（例如参数无效、资源未找到）
• 5xx — 服务器错误

达到限额

当你累计的请求数达到套餐的 request_limit 后，对任何计费或免费端点（/v4/account 除外）的后续调用都将立即返回：

HTTP/1.1 429 Too Many Requests

{
  "message": "Request limit exceeded",
  "details": "You have exceeded your request limit of X requests.",
  "code": "REQUEST_LIMIT_EXCEEDED"
}

你可以随时继续调用 /v4/account，以查看你的订阅、当前用量以及配额重置时间。

查询你的用量

你可以随时调用 GET /v4/account。响应将针对你的活跃订阅返回：

• request_limit — 你套餐的请求额度
• request_count — 当前周期内你已消耗的计费请求数量

减少请求消耗的建议

• 当底层数据变化不频繁时（例如 /v4/sports、/v4/bookmakers、/v4/markets、/v4/languages），请在客户端缓存响应。
• 尽可能批量请求 —— 当你一次需要多个赛事时，使用带过滤器的 /v4/fixtures，而不是多次单独调用。
• 合理轮询 —— 对计费端点的每次轮询都是 1 次请求，因此请将轮询间隔与数据实际变化的频率保持一致。