行銷 API

行銷 API 限速

行銷 API 有自己的限速邏輯，並且獨立於所有圖形 API 速率限制之外。因此，如果您發出行銷 API 呼叫，並不會計入圖形 API 節流內。

影響行銷 API 速率限制配額的功能是廣告管理一般存取權限。當您在應用程式主控板中新增行銷 API 產品時，預設會取得「廣告管理一般存取權限」的一般存取權限。這會提供您行銷 API 的開發存取權限。如果您需要升級以獲得更多限速配額，請在應用程式審查中升級為「廣告管理一般存取權限」的進階存取權限。

配額

行銷 API 存取權限廣告管理一般存取權限負載量

開發存取權限

一般存取權限

基本限速配額

一般存取權限

進階存取權限

更多限速配額

大部分行銷 API 要求和粉絲專頁 API 要求都受制於「企業使用案例（BUC）速率限制」，並視您查詢的端點而定。您可以檢查 HTTP 要求是否包含 X-Business-Use-Case 標頭，應該就會瞭解這一點。如需更多詳細資訊，請參閱企業使用案例速率限制。

廣告帳號層級 API 層級限制

  • 限速是在廣告帳號層級。
  • 速率限制會在給定時間範圍內即時發生。
  • 系統會為每個行銷 API 呼叫指派一個分數。您的分數為 API 呼叫總和。
  • 我們會強制執行分數上限。一般來說，讀取 API 呼叫等於 1 分，寫入 API 呼叫等於 3 分，當您達到分數上限時，我們會擲出節流錯誤。
    • 如果應用程式是在行銷 API 開發階層：
      • 分數上限為 60。
      • 衰減速率為 300 秒。
      • 如果達到分數上限，會被阻擋 300 秒。
    • 如果應用程式是在行銷 API 的標準階層：
      • 分數上限為 9000。
      • 衰減速率為 300 秒。
      • 如果達到分數上限，會被阻擋 60 秒。

相關錯誤代碼：17, Error subcode: 2446079, Message: User request limit reached. 613, Error subcode: 1487742, Message: There have been too many calls from this ad-account. Please wait a bit and try again.

廣告帳號層級 QPS 限速

為了防止流量突然爆發而導致系統過載，我們會針對行銷 API 變異端點（行銷活動、廣告組合和廣告的建立和編輯作業）實施即時限速。

  • 限速位於廣告帳號層級，針對每個應用程式實施。
  • 限制：每秒 100 個要求（QPS），針對每個應用程式和廣告帳號組合實施。
  • 適用於：行銷活動、廣告組合和廣告的建立和編輯作業。
  • 這項限制會即時生效，目的是在標準限速期間應對無法偵測到的短暫流量高峰。

下列端點會受到影響：

超出此限制後，請更均勻地將您的要求分散於不同時段，而不是一次提出大量要求。

相關錯誤代碼：613, Error subcode: 5044001, Message: Your ad account {ad_account_id} has exceeded the maximum allowed rate of mutation requests. To resolve this, reduce the frequency of your create, update operations on campaigns, ad sets, and ads.

遇到此錯誤時，請實作要求節流以將每個廣告帳號保持在 100 QPS 以下。

廣告洞察報告平台限速

  • 限速是在應用程式層級。
  • 限速取決於後端基礎設施和下游服務的負載量。
  • 當您的應用程式受到速率限制時，應用程式的所有廣告洞察報告 API 呼叫都會受到限制。
  • 系統會強制執行應用程式層級限速。

相關錯誤代碼：4, Error subcode: 1504022 or 1504039, Message: There have been too many calls from this app. Wait a bit and try again.

發生此錯誤時，請減少呼叫次數。

應用程式層級限制

  • 限速是在應用程式層級。
  • 限速取決於應用程式的總用戶數。
  • 當您的應用程式受到速率限制時，應用程式的所有呼叫都會受到限制。
  • 系統會強制執行應用程式層級限速。

相關錯誤代碼：4, Message: Application request limit reached

發生此錯誤時，請減少呼叫次數。

廣告帳號層級企業使用案例速率限制

我們會根據您的行銷 API 存取階層和應用程式計算速率限制配額。

  • 限速是在廣告帳號層級，而配額是根據您的應用程式廣告 API 存取階層來計算。
  • ads_management - 對於一小時期間內的每個廣告帳號：（如果您的應用程式是在行銷 API 標準階層，則為 100000；如果您的應用程式是在開發階層，則為 300）+ 40 * 刊登中廣告數。
  • custom_audience - 對於一小時期間內的每個廣告帳號：不超過 700000。（如果您的應用程式是在行銷 API 標準階層，則不少於 190000；如果您的應用程式是在開發階層，則不少於 5000）+ 40 * 活躍自訂廣告受眾數量。
  • ads_insights - 對於一小時期間內的每個廣告帳號：（如果您的應用程式是在廣告 API 標準階層，則為 190000；如果您的應用程式是在開發階層，則為 600）+ 400 * 刊登中廣告數 - 0.001 * 用戶錯誤數。
  • 目錄管理 - 對於一小時期間內的每個廣告帳號：20000 + 20000 * log2（不重複用戶）。
  • 目錄批次 - 對於一小時期間內的每個廣告帳號：200 + 200 * log2（不重複用戶）。
  • 您的行銷 API 速率限制也可能取決於廣告帳號的總 CPU 時間和總經過時間。如果您的應用程式具有行銷 API 一般存取權限，您會有更多配額。如需更多詳細資訊，請查看 HTTP [X-Business-Use-Case](/docs/graph-api/overview/rate-limiting/#headers-2) 標頭和企業使用案例速率限制。

相關錯誤代碼：80000, 80003, 80004, 80014, Message: There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.

驗證 API 端點和 HTTP X-Business-Use-Case 標頭，以確認節流類型。如需更多詳細資訊，請參閱企業使用案例速率限制。發生此錯誤時，請減少對廣告帳號的變更次數。

廣告帳號層級廣告花費速率限制

我們限制您每天只能變更帳號花費上限 10 次，以確保廣告投遞成效。

  • 變更廣告帳號花費（例如 spend_cap、spend_cap_action 欄位）的次數有所限制

相關錯誤代碼：17, Error subcode: 1885172, Message: You can only change your account spending limit 10 times per day. Please wait to make more changes.

廣告組合層級限制

變更廣告組合 daily_budget 和 lifetime_budget 欄位的次數有所限制。對於每個廣告組合，每小時只允許變更預算 4 次，如果超過限制，對該廣告組合進行的預算變更將會被封鎖一小時。

相關錯誤代碼：613, Error subcode: 1487632, Message: You can only change your ad set budget 4 times per hour. Please wait to make more changes.

發生此錯誤時，請減少對廣告組合的變更次數。

廣告層級限制

系統會根據每日花費上限，限制給定廣告帳號的廣告建立流程。

相關錯誤代碼：613, Error subcode: 1487225, Message: User request limit reached。

驗證錯誤子代碼（1487225）和 API 端點，以確認節流類型。發生此錯誤時，請減少變更次數。若要提高限制，您也可以增加每日花費上限。

濫用防範速率限制

當系統偵測到某些廣告帳號產生大量異常流量時，為了保護系統的穩定性及確保其他用戶的體驗，我們會暫時降低異常帳號的 API 速率限制配額。請嘗試聯絡 Meta 支援團隊尋求協助。

相關錯誤代碼：613, Error subcode: null, Message: (#613) Calls to this api have exceeded the rate limit.

此限制與「廣告帳號層級 API 層級限制」的差別，在於此錯誤不包含錯誤子代碼。發生此錯誤時，請調查是否有任何操作觸發過多 API 要求，並聯絡 Meta 支援團隊尋求協助。

處理節流錯誤

初步評估

檢查行銷 API 存取階層：

根據預設，應用程式具有行銷 API 的 development_access。若要瞭解您所在的階層，可以前往「應用程式審查」主控板。如果您有「廣告管理一般存取權限」功能的一般存取權限，則您是在行銷 API 存取權限的開發階層。如果您有「廣告管理一般存取權限」功能的進階存取權限，則您是在行銷 API 存取權限的標準階層。您也可以查看 HTTP 標頭，並在 X-Ad-Account-Usage、X-Business-Use-Case 或 X-FB-Ads-Insights-Throttle 標頭中尋找 ads_api_access_tier。

如果您一直收到限速錯誤，請考慮升級至「廣告管理一般存取權限」的 standard_access。若要達到標準階層並獲得更高的速率限制配額，您可以在「應用程式審查」主控板中申請「廣告管理一般存取權限」功能的進階存取權限。

  • 檢查錯誤代碼：在 API 回應中判斷是否有與節流相關的特定錯誤代碼。
  • 檢查 HTTP 標頭：
    • X-Ad-Account-Usage 包含 acc_id_util_pct、reset_time_duration 和 ads_api_access_tier。
    • X-Business-Use-Case 包含「企業使用案例」端點的 call_count、total_cputime、total_time 和 estimated_time_to_regain_access 等資訊。
    • X-FB-Ads-Insights-Throttle 包含廣告洞察報告 API 端點的 app_id_util_pct、acc_id_util_pct 和 ads_api_access_tier。
  • 檢查應用程式主控板：我們在「應用程式主控板」中提供主控台，為開發人員提供限速系統的深入洞察報告，協助他們診斷和預防限速問題。

識別原因

  • 速率限制：瞭解所使用之各種端點的 Meta 行銷 API 速率限制，並確認 API 要求數量是否在應用程式允許的限制範圍內。
  • 突發限制：檢查突發限制是否在用量高峰時間造成問題。通常突發流量會導致「廣告帳號層級 API 層級限制」（相關錯誤代碼：17、613）。
  • 操作錯誤：調查是否有任何操作錯誤觸發過多 API 要求。

緩解步驟

  • 防止突發流量：平均分配 API 要求，以避免因短時間內大量存取所造成的節流。
  • 最佳化要求：將多個較小的要求合併成批次要求（編號批次或非同步要求），以儘量減少 API 呼叫總數。
  • 退避策略：在收到節流錯誤時實作指數退避，逐漸增加重試的間隔時間。您也可以檢查 HTTP 標頭以估計重設時間。

其他緩解技巧

  • 瞭解是否需要這些通話，並在不需要時減少通話。
  • 對於支援非同步要求的端點（例如廣告洞察報告 API），可以使用非同步要求來查詢大量資料。
  • 如果您需要查詢多個相同類型的廣告物件，也可以嘗試傳遞編號清單。
  • 對於洞察報告 API，可以使用層級參數或過濾方式來減少呼叫次數。