Talent Summoner向廠商
一份不偏向任何廠商的 API 速率限制（API rate limit）問題清單，涵蓋配額、429、重試、並行、監控、成本，以及招募營運試行的決策。
一個 API 在展示時可能看起來很快，但當招募團隊在早上跑一批匯入、重新整理入圍名單，或重試一次逾時的寫入時，它還是可能出問題。請廠商說明：計算的是什麼、在多長的時間窗口內、針對哪個身分，以及用戶端接下來該怎麼做。這份指南寫給正在比較廠商或排查速率限制問題的招募營運主管。它不是容量保證，也不是資安評估。在答案有書面紀錄、註明日期並經過測試之前，一律標為未知。
從一個可重現的情境開始
把同一個小型情境寄給每一家入圍的廠商。寫清楚端點或工作流程、請求數量、酬載大小、頁數、尖峰模式、並行的 worker 數量、環境、地理位置，以及請求是讀取還是寫入。詢問報價方案的限制，以及答案的出處：最新文件、合約、儀表板或測試結果。
在第一次審查時使用這個問題：
就這個情境而言，適用哪些限制？用戶端要如何觀察到這些限制？達到限制時會收到什麼回應？在不產生重複或遺漏紀錄的前提下，支援哪些復原方式？
不要把每分鐘的數字和每日配額當成同一種單位來比較。問清楚某個限制是硬性、軟性、共用、另外計量，還是受合理使用條款約束。記下方案名稱、文件版本和回答日期，因為限制可能因端點、環境或帳號而不同。
揭露真正限制的問題
| 面向 | 要問廠商的問題 | 要索取的證據 |
|---|---|---|
| 配額單位 | 限制是以 API 金鑰、組織、使用者、IP、端點、資源還是方案為單位？讀取、寫入、搜尋和匯出是否分開計算？ | 報價方案的限制表，包括適用範圍和排除項目 |
| 時間窗口 | 窗口是固定、滑動、權杖桶（token bucket），還是其他演算法？什麼時候重置？沒用完的額度能不能累積到下一期？ | 白話的定義、時間戳記和一個小型測試結果 |
| 突發量 | 安全的突發量或短期額度是多少？突發是否會消耗較長期的配額？ | 突發範例，包含請求間隔、回應標頭和觀察到的次數 |
| 並行 | 同時進行中的請求、連線、工作或頁面有沒有上限？超過時會發生什麼事？ | 並行上限、佇列行為和錯誤格式 |
| 回應 | 額度用完的請求是否回傳 429 Too Many Requests？是否帶有 Retry-After？它是以秒數還是 HTTP 日期表示？是否適用於所有用戶端？ | 遮蔽敏感資訊後的回應，包含狀態碼、標頭、內容和請求 ID |
| 速率標頭 | 是否回傳 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset？它們描述的是哪個範圍和單位？ | 標頭定義，以及在低用量和高用量時擷取的回應 |
| 分頁 | 每一頁都算一次請求，還是其他單位？重試時游標是否穩定？能否安全地從某一頁繼續？ | 分頁和游標規則、單頁上限，以及一次重放測試 |
| 重試安全 | 哪些失敗可以安全重試？廠商建議怎樣的退避（backoff）和抖動（jitter）？ | 針對 429、5xx、逾時和連線失敗的重試指引 |
| 寫入 | 有沒有冪等性金鑰或其他去重方法？保留多久？重放時回傳什麼結果？ | 冪等性規格，以及逾時後的寫入測試 |
| 監控 | 客戶能否看到用量、剩餘配額、延遲、429 次數和失敗的重試？有沒有警示或 webhook？ | 儀表板欄位、匯出／API、保存期限和警示負責人 |
| 升級處理 | 持續觸及限制、發生事故或限制無故調降時，由誰處理？需要提供哪些資訊？適用什麼回應時限？ | 支援管道、嚴重程度定義和合約服務條款 |
| 成本 | 什麼會產生計費單位：請求、紀錄、頁面、位元組、工作、席次還是超額用量？重試要不要收費？ | 針對這個情境、註明日期的報價、超額用量規則和範例帳單 |
IETF 的 RateLimit 標頭欄位規格於 2023 年 8 月發布，為限制、剩餘額度和重置時間提供了一套用語，但它不強制要求這些欄位，也不能證明廠商已經實作。RFC 6585 於 2012 年 4 月發布，定義了狀態碼 429；RFC 9110 於 2022 年 6 月發布，定義了包括 Retry-After 在內的 HTTP 語意。用這些註明日期的參考資料讓問題更精確，而不是用來推斷廠商的實際行為。
不靠猜測排查速率限制
用戶端收到 429 時，保存時間戳記、端點、方法、請求 ID、標頭、內容、用戶端身分、並行數和本機的配額計數。檢查有沒有指定重試時間。遵守有效的 Retry-After；如果沒有，就使用有上限的指數退避，加上抖動、嘗試次數上限和斷路器。把用完額度的工作轉到持久化佇列或人工審查，避免重新啟動時無聲無息地跳過它。
把可重試的傳輸失敗和已被接受的非同步請求分開。寫入後發生逾時，結果是不明確的：先查詢該資源，或用廠商的冪等性機制重放，再決定要不要建立另一筆紀錄。問清楚冪等性金鑰的範圍是端點、帳號還是酬載，以及同一把金鑰搭配不同內容重複使用時會發生什麼事。結構化的錯誤能幫助用戶端判斷回應的類型；RFC 9457 於 2023 年 7 月發布，說明了 HTTP Problem Details，但這不代表廠商一定採用這種格式。
分頁和並行常常把失敗藏起來。測試跨越分頁邊界的結果集、過期的游標、兩頁之間被修改的紀錄，以及 worker 重新啟動。測量同時進行中的請求、分頁缺口、重複紀錄、延遲和 429 回應。如果廠商只說「請使用合理的流量」，就請對方給出具體的數字上限，否則把這項試行條件標為未解決。
帶著停止條件進行招募試行
示範情境：一位招募營運主管正在評估某家廠商的 API，用它為一個核准的職缺補充 200 筆虛構的候選人紀錄。試行設定每頁 20 筆紀錄、兩個 worker、一次 10 個請求的突發、一次強制觸發的 429、一次寫入後的逾時，以及從儲存的游標繼續。測試中沒有任何真實的履歷或聯絡方式。主管記錄方案、請求數和頁數、時間戳記、狀態碼和速率標頭、請求 ID、重複紀錄、遺漏紀錄、重試延遲、警示和廠商回應。這是測試用的固定資料，不是容量基準。
試行之前，先約定最後一份已知正常的匯出檔、佇列或游標、冪等性做法、負責人和復原動作。復原可以是暫停呼叫、隔離佇列中的工作、還原欄位對應，或改為人工審查；但不應該無聲無息地刪除紀錄。遇到以下情況就停止：429 無法被控制在範圍內、Retry-After 語意不明又沒有備援做法、逾時的寫入無法對帳、分頁可能跳過紀錄、監控沒有負責人，或報價漏掉某個計費單位。只有在有指名的負責人、到期日和經授權的例外時，才繼續進行。
使用這份精簡的決策紀錄：
廠商 API 速率限制審查
廠商、API／版本、方案和回答日期：
情境、環境、端點和預期用量：
配額範圍、單位、時間窗口、突發量和並行數：
429、Retry-After、速率標頭和錯誤內容的證據：
分頁、游標、重試和冪等性的證據：
用量儀表板、警示、請求 ID 和保存期限：
支援管道、升級處理條款和負責人：
廠商費用、超額用量、重試收費和內部工作量：
試行用的固定資料、觀察結果和已知缺陷：
復原、人工備援和停止條件：
決定：PASS / PILOT WITH CONDITIONS / STOP
負責人、例外到期日和下次回顧日期：Talent Summoner 適合放在哪裡
Talent Summoner 是我們做人才搜尋和候選人排序的產品，不是通用的 API 整合工具，也不是 ATS。人才搜尋從一份核准的職缺需求說明開始，回傳從公開來源發掘的人選，交給人審閱。候選人排序審閱你提供的履歷。這兩個頁面都沒有提到 API 配額、webhook、應徵者人才管道管理或雙向同步，所以不要假設它有這些功能。主動聯繫是另一項功能：Talent Summoner 會草擬每一則訊息，由你審閱並確認寄出後，才從你連結的 Gmail、Outlook 或 LinkedIn 帳號寄出。匯出或人工交接都交給招募營運負責人處理；等這條界線清楚之後，再查看價格。
向廠商詢問 API 速率限制時，第一個該問的問題是什麼？
問清楚計算的是什麼、範圍和時間窗口、安全的突發量和並行數，以及達到限制時確切的回應和復原方式。請對方針對你的方案和情境，提供註明日期的答案。
有 `Retry-After` 就足以讓 API 可靠嗎？
不夠。用戶端還需要有上限的退避、抖動、重試次數上限、持久化的工作佇列、監控，以及針對寫入和分頁的對帳。一個標頭並不能證明重試是安全的。
成本模型應該把重試算進去嗎？
要明確詢問。不同方案的廠商可能會用不同方式計算請求、紀錄、頁面、位元組或工作。請對方提供書面報價，把預期的失敗和超額用量處理方式都算進去；不要假設重試是免費的。
招募營運的試行應該測試什麼？
用虛構的紀錄測試一般分頁、一次突發、強制觸發的 429、寫入逾時、重複重放、游標續傳、worker 重新啟動、監控警示和人工備援。在使用正式資料之前，先記錄證據和停止條件。
Talent Summoner 有提供 API 速率限制處理或 ATS 整合嗎？
它文件記載的範圍是人才搜尋和候選人排序。它沒有宣稱提供通用的 API 整合或 ATS 同步功能。任何下游的匯出、查證和錄用決定，都由你的團隊負責。
把一個具代表性的工作流程拿給每家廠商，保留註明日期的回答和原始測試證據，再選擇 PASS（通過）、PILOT WITH CONDITIONS（有條件試行）或 STOP（停止）。上游的人才發掘，可以參考人才搜尋；已經拿到的履歷，就用候選人排序，並把整合審查分開進行。
