速率限制

各方案在 Listings 與 Social 間共用的請求限制、429 回應格式，以及如何退避並重試。

Listings API 會依帳戶計算請求數，並套用您方案的速率限制。將請求數維持在限制內，可讓您的整合保持即時回應；超過限制時，API 會傳回 429 Too Many Requests，其中包含妥善重試所需的所有資訊。

各方案的限制

還沒有付費方案，想先試用 API 嗎？啟用免費沙箱單日通行證時，您會收到 API 金鑰，以及該通行證目前適用的請求限制。

限制依方案而定，並以帳戶為單位實施：同一帳戶的所有 API 金鑰都共用相同的配額。請求數會依三個時間範圍計算：每分鐘的突發請求限制、每小時限制，以及每日上限。無論使用哪個端點，每次請求都消耗相同的配額。免費試用會採用您選擇的方案，因此從第一次請求起，就會套用該方案的限制。

方案	每分鐘限制	每小時限制	每日限制
Launch	每分鐘 10 次請求	每小時 600 次請求	每日 7,200 次請求
Growth	每分鐘 50 次請求	每小時 3,000 次請求	每日 36,000 次請求
Enterprise	依合約設定	依合約設定	依合約設定

Social 端點與其他所有端點共用同一份帳戶請求配額。包含 500 筆資料的 POST /social/bulk-posts 只計為一次請求，而非 500 次，因此大量處理是載入大量內容時最節省配額的方式。

Listings 與 Social 是各自獨立的訂閱，但請求配額並非各自獨立。同時持有兩種訂閱的帳戶會採用兩個方案級別中較高的限制，並在所有端點間共用這一份配額，而非將兩者相加，也不是每項產品各有一份配額。訂閱 Listings Launch 與 Social Growth 的客戶，其所有流量都會依照上述 Growth 的數值計算。

429 回應

當您超過限制時，API 會傳回 HTTP 429 及標準錯誤回應。有三個欄位與重試相關：

retry_after_seconds：重試前需要等待的時間。若回應包含 Retry-After HTTP 標頭，其值會與此欄位相同。
correlation_id：聯絡支援團隊時可提供的請求識別碼。
doc_url：指向錯誤代碼參考文件中 rate_limited 項目的連結。

JSON

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

以退避策略處理 429 回應

若有 retry_after_seconds，請依其指定的時間等待；否則，請採用指數退避：每次連續收到 429 時，將延遲時間加倍，直到達到上限，並加入少量隨機抖動，避免大量用戶端同時重試。

Python

import randomimport time import requests MAX_RETRIES = 5  def get_with_backoff(url: str, headers: dict, max_retries: int = MAX_RETRIES):    for attempt in range(max_retries):        resp = requests.get(url, headers=headers)        if resp.status_code != 429:            resp.raise_for_status()            return resp.json()         # Prefer the server's hint; fall back to exponential backoff + jitter.        body = resp.json().get("error", {})        retry_after = body.get("retry_after_seconds")        if retry_after is None:            retry_after = min(2 ** attempt, 30) + random.uniform(0, 1)        time.sleep(retry_after)     raise RuntimeError("Still rate limited after retrying")

將請求數維持在限制內

一次只請求一頁：密集的平行分頁迴圈是最常造成 429 的原因。請讀取 pageInfo.hasNextPage，並在目前頁面的回應傳回後，才擷取下一頁。
使用 filter 查詢參數在伺服器端篩選資料，而非擷取所有頁面後，再於用戶端捨棄資料列。
將不常變動的回應快取起來，避免每次請求都重新擷取。