金鑰、額度與錯誤
了解如何傳送金鑰、方案包含哪些 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）。
- 私人網段和回送 (loopback) 地址會被拒絕——本 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 次免費賽程列表請求。真實數據，毋須信用卡。