マーケティングAPIのレート制限

マーケティングAPIには独自のレート制限ロジックがあり、すべてのグラフAPIのレート制限から除外されます。そのため、マーケティングAPI呼び出しを実行しても、グラフAPIのスロットリングの計算には含められません。

マーケティングAPIレート制限クォータに影響する機能は、広告管理スタンダードアクセスです。アプリダッシュボードにマーケティングAPI製品を追加すると、デフォルトの場合、広告管理スタンダードアクセスのスタンダードアクセスになります。これにより、マーケティングAPIへの開発用アクセスを得ることができます。レート制限クォータを増やすためにアップグレードする必要がある場合は、アプリレビューで広告管理スタンダードアクセスのAdvanced Accessにアップグレードしてください。

クォータ

マーケティング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のミューテーションのエンドポイント(キャンペーン、広告セット、広告の作成と編集)にリアルタイムのレート制限を適用しています。

• レート制限は、アプリごとに広告アカウントレベルで適用されます。
• 制限: アプリと広告アカウントの組み合わせごとに、1秒あたり100リクエスト(QPS)。
• 適用: キャンペーン、広告セット、広告の作成と編集の操作。
• この制限はリアルタイムで動作し、標準のレート制限時間枠では検出できない短期間のトラフィック増加を検出するようになっています。

以下のエンドポイントが影響を受けます。

• POST /{ad-account-id}/ads
• POST /adgroup
• POST /{ad-account-id}/adsets
• POST /adcampaign
• POST /{ad-account-id}/campaigns
• POST /campaigngroup

この制限を超える場合は、リクエストを一括で送信するのではなく、時間をあけてより均等に送信してください。

関連エラーコード: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 - 広告アカウントごとに1時間あたり、(アプリがマーケティングAPIスタンダードレベルの場合は100000、アプリが開発レベルの場合は300) + 40 ×アクティブな広告数。
• custom_audience - 広告アカウントごとに1時間あたり、700000以下。(アプリがマーケティングAPIスタンダードレベルの場合は190000、アプリが開発レベルの場合は5000) + 40 ×アクティブなカスタムオーディエンスの数。
• ads_insights - 広告アカウントごとに1時間あたり、(アプリが広告APIスタンダードレベルの場合は190000、アプリが開発レベルの場合は600) + 400 ×アクティブな広告数 - 0.001 ×ユーザーエラー数
• カタログ管理 - 広告アカウントごとに1時間あたり、20000 + 20000 × log2(異なるユーザー数)。
• カタログ一括 - 広告アカウントごとに1時間あたり、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ヘッダーを確認して、スロットリングタイプを確かめます。詳しくは、ビジネスユースケースレート制限をご覧ください。このエラーが発生した場合は、広告アカウントに対する変更回数が少なくなるように調整してください。

広告アカウントレベルの広告費用レート制限

広告配信のパフォーマンスを確保するため、アカウントの費用制限の変更は1日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フィールドに対する変更回数は制限されています。広告セットごとに予算の変更は、1時間あたり4回のみ許可されています。上限を超えた場合、その広告セットの予算変更は1時間ブロックされます。

関連エラーコード:613, Error subcode: 1487632, Message: You can only change your ad set budget 4 times per hour. Please wait to make more changes.

このエラーが発生した場合、広告セットに対する変更回数が少なくなるように調整してください。

広告レベルの制限

特定の広告アカウントでは、1日の上限予算に基づいて広告作成が制限されます。

関連エラーコード:613, Error subcode: 1487225, Message: User request limit reached.

エラーサブコード(1487225)とAPIエンドポイントを確認して、スロットリングタイプを確かめます。このエラーが発生した場合、変更の規模を抑えるように調整してください。上限を大きくするには、1日あたりの費用制限を大きくすることもできます。

不正使用防止レート制限

特定の広告アカウントで大量の異常トラフィックが発生していることが検出された場合は、システムの安定性を維持し、他のユーザーのエクスペリエンスを確保するため、異常アカウントの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などの非同期リクエストをサポートするエンドポイントの場合、膨大な量のデータのクエリには非同期リクエストを使ってください。
• 同じタイプの複数の広告オブジェクトへのクエリを実施する必要がある場合は、IDのリストを渡すこともできます。
• インサイトAPIの場合は、レベルパラメーターまたはフィルタリングを使うことによって、呼び出し回数を減らしてください。