密钥、额度与错误
了解如何发送密钥、方案包含哪些 API、请求如何计算，以及错误的含义。
本页内容
密钥
把密钥放在 Authorization 头，格式为 Bearer <key>。也可以用 X-Api-Key 头。切勿把密钥放在网址内。
Authorization: Bearer tsm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- 所有方案每个账户最多持有一条未撤销的 API 密钥。已过期的密钥仍占用名额，须先撤销。撤销或更换密钥不会重置账户的每日用量。
- 创建时请复制完整密钥，之后无法再次查看。
密钥期限及变更
- 密钥会在仪表板列出的日期到期。API 权限按账户当前方案决定，即使密钥的 tsm_test_ 或 tsm_live_ 前缀是在另一方案下签发，也不影响当前方案权限。
- 方案及白名单变更最多需 60 秒生效。撤销密钥则立即生效。
两种限额，而不是一种
每个账户有每日额度，即每天可发出的请求次数。额度在香港时间 00:00（UTC 16:00）重置。每个密钥另有每分钟上限。更换密钥不会重置当日用量。
达到每分钟限制时会返回 429 及 Retry-After。请等待后重试；被拒绝的请求不会使用每日额度。
每日免费赛程列表请求
所有方案每个香港日另有 GET /v1/football/matches 免费请求：免费 50 次、Plus 500 次、Pro 2000 次。会先于方案额度使用。/matches/live 及比赛详情等路径使用方案额度。免费额度于香港时间午夜重置，更换密钥不会重新获得额度，且仍受每分钟上限限制。此端点的 X-Matches-Bonus-* 头会显示这部分额度。
响应头
| 请求头 | 含义 |
|---|---|
| X-RateLimit-Limit | 本分钟内允许的请求数。 |
| X-RateLimit-Remaining | 本分钟内还剩多少次。 |
| X-RateLimit-Reset | 距离本分钟结束还有多少秒。 |
| X-Quota-Limit | 账户的每日请求上限，不包括独立的免费赛程额度。 |
| X-Quota-Remaining | 账户今日剩余请求次数，已计入被撤销密钥的用量。 |
| X-Quota-Reset | 距离香港时间 00:00（16:00 UTC）还有多少秒。 |
| X-Matches-Bonus-Limit | 每个账户每日额外免费 GET /v1/football/matches 请求上限，仅此端点提供。 |
| X-Matches-Bonus-Remaining | 账户今日剩余免费赛程请求次数，会先于方案额度使用。 |
| X-Matches-Bonus-Reset | 距离免费赛程额度于香港时间 00:00 重置的秒数。 |
需要更多请求？各方案的额度见 价格页。
IP 白名单
IP 白名单为可选设置，按密钥管理。留空代表允许任何 IP 使用。如需限制访问，请填写服务器实际对外连接的 IP 地址。
- 支持单个地址或 CIDR 段，范围不得大于 /24（IPv4）或 /48（IPv6）。
- 私有地址段和回环地址会被拒绝——本 API 不可能看到它们。
- 被拒绝时响应会回显它实际看到的地址，你可以直接把它加进去，不必猜测平台用了哪个出口。
响应格式与分页
大部分端点在 data 下返回 JSON。/matches 另附分页 meta；/matches/live 不分页。/odds/exchange 直接返回已存储的 JSON。kickoffUtc 使用 ISO-8601 UTC，历史分析日期保留存储格式。缺失的可选字段会省略。请按各端点的响应结构读取数据。
"meta": { "page": 1, "pageSize": 25, "total": 38, "totalPages": 2 }/matches 的 page 从 1 开始；pageSize 默认为 25，最多 100。
错误码
错误以 JSON 返回，内含 code 字段。程序请判断 code；文字信息可能会改变。
错误响应示例
{
"type": "https://tipsme.hk/developers/docs/errors#quota_exceeded",
"title": "Daily quota exceeded",
"status": 429,
"detail": "This account allows 5000 plan requests per day. The quota resets at 00:00 Hong Kong time (16:00 UTC).",
"code": "quota_exceeded"
}| 状态码 | code | 含义 |
|---|---|---|
| 400 | invalid_parameter | 某个参数未通过校验，响应正文会指明是哪一个。 |
| 401 | unauthorized | 没有发送密钥。 |
| 401 | key_invalid | 密钥不存在或已被吊销。 |
| 403 | key_expired | 密钥已过期。 |
| 403 | tier_insufficient | 分析需要 Plus 或 Pro API 密钥。免费密钥会收到 403，且不扣除每日额度。其他已公布端点适用于所有方案。 |
| 403 | ip_not_allowed | 调用方地址不在该密钥的白名单内。 |
| 404 | not_found | 资源不存在。 |
| 409 | key_limit_reached | 此账户已持有一条 API 密钥。请先撤销，才可创建另一条。 |
| 409 | allowlist_limit_reached | 该密钥的白名单条目已达上限。 |
| 429 | rate_limited | 超出每分钟限流，请参考 Retry-After。 |
| 429 | quota_exceeded | 账户的每日方案额度已用尽，于香港时间午夜（UTC 16:00）重置。 |
| 502 | upstream_malformed | 上游有响应，但内容无法解析。 |
| 503 | upstream_unavailable | 某个数据源暂时不可达，请重试。 |
由免费方案开始
一个 API 密钥，每个账户每日 30 次请求，另加每日 50 次免费赛程列表请求。真实数据，无需信用卡。