Marketing Cloud Engagement の提供する API を利用するときに考慮する事項と FAQ

本ドキュメントでは、Marketing Cloud Engagement の API 連携を安定的に実行するための設計指針をまとめました。

検討のポイント

Point 1 : 自動でのリトライを実装する (重要)

API リクエストに対して、一時的なエラー（主にHTTP Status Code が 500や 429 など）が応答される場合があります。その要因は API サービスの一時的な負荷などに加え、インターネット経路上の問題などさまざまですが、実際の利用では少なからず一時的なエラーは不可避で必ず不定期的に遭遇します。そのため、一時的なエラーが発生することをあらかじめ想定しておき、リトライの仕組みを実装する必要があります。

具体的には API リクエストを発行するアプリケーションで、想定しうるエラーハンドリングの処理を追加します。そして、500番台のエラーが発生したときに適切な回数・タイミングで API リクエストのリトライを自動で行う仕組みを実装します。このときリクエストを再送する際には、前後の処理を含め二重で処理実行してしまわないか、想定した結果から変わってしまわないかと言った観点でのハンドリングが不可欠です。

一方で、400 Bad Request や 401 Unauthorized といった、クライアント側のリクエスト内容に問題があるケースでは、何度リトライしても基本的に成功することはありません。この場合は自動リトライを停止し、エラーメッセージを元にリクエスト内容を修正した上で再送してください。

Point 2 : API クライアントでのタイムアウト時間の調整を検討する (中継機器を含む)

Point 3 : 詳細なログを残す (ただし秘密情報は除く)

Point 4 : トークンの取得を最小限に抑え、有効期限内は再利用する

1 つの処理を実行するたびにトークンの取得 (POST /v2/token) を行うと、リクエスト数が単純に約 2 倍になり全体のリクエスト数を無駄に増加させる原因となります。リクエスト数が多いと、一時的なエラーやリクエスト制限に抵触しやすくなります。当社APIのアクセストークンは 20 分の有効期限 があるため、取得したトークンを有効期限内で可能な限り再利用することを検討します。

Point 6 : エンドユーザー端末（ブラウザやモバイルアプリ）からの直接 API 実行を回避する

ブラウザやモバイルアプリ端末から直接 API を実行する構成は、以下例のような問題を伴うため、原則として「サーバーを中継する構成」を強く推奨します。

・セキュリティ :  API を実行するための認証情報（クライアントIDやシークレット）をアプリ側に保持させることは、悪意のある第三者による「なりすまし」や「不正利用」のターゲットとなる高いリスクを伴います。一度アプリに埋め込まれたこれらの情報は容易に抽出でき、お客様側で完全に制御・隠蔽することは困難です。

・保守性の低下 : 当社APIの変更やバージョンアップが必要になった際、全てのユーザーに対してアプリのアップデートを強制しなければならず、移行完了までに多大な時間とコストを要します。この問題に対し、中継サーバーを介在させることでAPIの変更をサーバー側で吸収することが可能となり、クライアント側に依存しない柔軟なシステム改修を実現できます。また、Client Secret が180日で失効するという制約があり、クライアントが直接シークレットを保持する仕組みを一度採用してしまうと、モバイルユーザーは常に有効なシークレットを含む最新バージョンへ更新し続けなければなりません。これは、アプリ提供者側におけるリリース管理の煩雑化を招くだけでなく、エンドユーザーに対しても継続的なアップデートを強いることになります。

・エンドユーザー体験（UX）への悪影響 : ネットワークの瞬断や API サービス側のメンテナンス時に、端末から直接リクエストしていると、画面のフリーズや不整合なデータ表示が直接発生する可能性もあります。中継サーバー側でキャッシュの利用や、エラー時の代替表示の制御を行うことで、エンドユーザーへの影響を最小限に抑えることが可能です。

Point 7 : リクエスト頻度の適正化と 429 エラー (Rate Limit) について検討する

システム全体の安定稼働を維持するため、特定のアカウントから短期間に大量のリクエストが行われた場合、API は HTTP 429 Too Many Requests エラーを返し、一時的にリクエストを制限（スロットリング）します。この場合、以下を参考に可能な限り安定的な利用を検討します。

• Retry-After ヘッダーを遵守する :  429 エラーが返された場合、レスポンスヘッダーに含まれる Retry-After の値（秒数）があるか確認してください。この時間を無視して即座にリトライを繰り返すと、繰り返し 429 が返される場合があります。

• トラフィックの平準化（ピークの分散） API 制限のしきい値は動的です。全体の流量が上限以内であっても、特定の一瞬（例：毎時 00 分 00 秒など）にリクエストが集中するスパイクが発生すると、制限の対象となりやすくなります。処理の開始時間を意図的にずらすなどして負荷を平準化できないか検討します。

• リクエスト回数の削減（バッチ化） ：前述のアクセストークンを毎回取得しないことに加えて、可能なものについては一斉に送信できないか検討します。（例：Send email message to multiple recipients で複数の受信者を一括で送信するなど)

そのほか、下記のベストプラクティスもあわせて参照してください

Title : Prevent Rate-Limiting

URL :  https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/rate-limiting-best-practices.html

問い合わせ起票時の提供推奨情報

API リクエストのエラーに関して当社サポートへ調査をご依頼（ケース起票）される際は、迅速かつ正確な原因特定のため、以下の情報をご提供ください。 複数回発生している場合は、同じエラーの代表的なものを 2〜3 件程度サンプリングしていただく形で構いません。

・リクエストの基本情報（日時・メソッド・URL）

いつ、どこに対して、どのような操作を行ったかを特定するために必要です。リクエスト日時（タイムゾーン含む）、URL、HTTPメソッドを添えてください。

・HTTP 通信ログの詳細（ヘッダー・ボディ）  

リクエストとレスポンス双方の「全ヘッダー」および「ボディ」をご提供ください。これらはエラーの具体的要因（設定ミスや制限値への抵触など）を特定するための一次情報となります。

[NOTE]

・セキュリティ保護のため、アクセストークン、クライアントシークレット、個人情報は必ずマスキング（*** などで置換） やハッシュ化または削除してください。

・散発的な500 エラーの場合は後述通り、一時的な問題に起因することが多いため、直近で相対的に頻度が増えてきた場合に詳細調査の検討を推奨します。もし増加が見られる場合は、いつ頃からどの程度増加しているなどのおおよその傾向をご申告ください。

問い合わせでよく発生する状況 1：APIクライアント/サーバー間のエラー確認数の差異

APIクライアント側で記録されたエラーの内容や発生回数と、当社（MCE）側で記録されているエラーの発生回数に差異が生じる場合があります。

【よくある例】

• API クライアントでの 500 エラー記録数 = 10 回

• 当社（MCE）側での 500 エラー記録数 = 0 回

このようなケースでは、Point 2で触れた「貴社ネットワーク内のプロキシサーバー」や「経路上の中継機器（WAF、API Gatewayなど）」がタイムアウト等の理由で独自にエラーを発生させ、当社に到達する前に通信を遮断している可能性が極めて高いです。エラーの発生源が当社か中継機器かを見分けるため、Point 3で取得を推奨している「詳細な通信ログ」が役立ちます。例えば、レスポンスボディの形式が当社APIが返すエラーではあまりみられないような何らかのNW機器固有の情報が含まれているケースです。このような特徴が確認された場合は、当社へお問い合わせいただく前に、貴社のネットワーク管理者様へ経路上の機器のログをご確認いただくことを推奨します。

問い合わせでよく発生する状況 2：500 エラー が応答される原因についての詳細調査依頼について

HTTP 500 エラーは、当社サービス内部の一時的な問題だけでなく、インターネット経路上の不安定な状態、中継機器の瞬断、あるいはクライアント側のタイムアウト設定など、多岐にわたる外部要因によって誘発される場合があります。

これらの中には、原因の特定が困難、あるいは特定できても対策が「再試行」以外にないケースが多く含まれます。より重要なエラーに集中して対応を優先づけできるよう、調査をご依頼いただく前に以下の基準での切り分けをお願いしております。

1. 一過性の事象（詳細調査による原因特定が困難なケース）

ネットワーク経路上の一時的な混雑など、「一定の確率で不可避に発生する」エラーです。これらは事後調査を行っても、ログに明確なエビデンスが残らず「原因特定不能」という回答に至る可能性が極めて高いものです。

• 発生傾向の例:

  • 低頻度・非連続： 数分間に数リクエストのみ失敗する、または数日間に数回程度、不規則に発生する。

  • 非再現性： 同一条件で再試行（リトライ）を実行すると正常に成功する。

• 本ケースへの考え方: 低頻度で散発的に発生する事象は、膨大なシステムログの中から特定の通信を追跡する作業に多大な工数を要する一方、その多くはシステム障害など MCE の恒常的な問題に起因するものではありません。 そのため、個別調査を行っても「原因特定不能」あるいは「不可避な一過性の外部要因」「局所的な過負荷」という結論に至る可能性が高く、多くのケースでは回答までにお時間をいただき、また回避策はリトライを推奨する旨のご案内となります。 

• 推奨される対策: クライアント側アプリケーションにて、指数バックオフ等のアルゴリズムを用いた自動リトライ処理の実装を検討してください。エラーを自動回復させることで、業務影響を最小限にし、安定した利用継続が可能となります。また、個々の成否のみを断片的に追跡せず、エラー発生数の推移をモニタリングし、「以前より明らかに増加傾向にないか」「これまでみたことがないようなエラー内容が応答されていないか」といった全体的な傾向や変化に着目することを推奨します。(これにより次項のような対応を要する事象かどうかの切り分けにもつながります）

2. 継続的・再現性のある事象（詳細調査が有効なケース）

明確な異常傾向が確認され、サーバー側の問題や処理の精査によって原因を特定できる可能性が高いケースです。

• 発生傾向の例:

  • 高頻度・持続性： HTTP 500 エラーの発生率が平時より明らかに上昇し、自然復旧せず継続している。

  • 完全な再現性： 特定の操作やパラメータの組み合わせにおいて、100%（または高確率）でエラーが再現する。

• 本ケースへの考え方: システム側の不具合やリソースの過負荷や、APIの論理的な誤りなど恒常的な問題が疑われます。速やかに原因を特定するため、前述の"問い合わせ起票時の提供推奨情報"をもとに情報を確認のうえ調査をご依頼ください。

*本セクションに記載の一時的なネットワークの散発的なエラーは、API に限らず SFTPなど Web を経由するあらゆる通信に共通します。（SFTPに関しての記事)

*お問い合わせいただいた場合、当社が提供している API 関連のサービスの問題有無の調査が主な対象となります。

FAQ

Q) リトライ方式の推奨はありますか?
A) ケースバイケースですが、試行回数のたびに徐々に実行間隔を大きくしていく(例: 3 秒後、10 秒後、60 秒後…) 指数バックオフやランダムな遅延を取り入れることを推奨します。

また429 エラーで当社サーバーから Retry-After ヘッダー（再試行までの待機秒数）が返却された場合は、ご自身で計算したバックオフ時間よりも Retry-After の値を優先し、指定された時間を待機します。

1. 送信リクエストのレスポンスから messageKey を取得
2. Retrieve status of an email message で送信結果を確認
3. 未送信の場合のみリトライを実行

Q) リクエスト数上限やタイムアウトなどの制限について教えてください
A) 当社APIの基本的な制限事項は下記「API Limits and Guidelines」に記載されています。ただし、この制限内であっても、短期間に負荷の大きなリクエストを多数実行した場合は一時的な制限（429 Too Many Requests）がかかる場合があります。

参考1) API Limits and Guidelines
参考2) Rate Limiting Errors

Q) 429エラーが発生する具体的な「上限値」はいくつですか？

A) 固定の上限値は公開されていません。制限のしきい値は、その瞬間のシステム全体の負荷状況や、リクエストの処理内容（データベースへの負荷など）に応じて動的に変動します。そのため、通常と同程度の流量であっても状況により一時的に 429 が返される場合があります。 Point 4（トークンの再利用）や Point 7（ピークの分散）を実施しても明らかに頻発する場合は、発生状況と詳細なログを添えてサポートへお問い合わせください。

Q) API クライアントの実装方法（PythonやcURLでの書き方や設定方法）についてサポートしてもらえますか？ 
A) プログラミング言語や外部ツールに依存する実装・記述方法については、サポートケースでの正式回答をいたしかねます。特定の実装に依存するエラーが MCE の挙動に起因する問題と思われる場合は、切り分け結果や、実際に送信された生のHTTPリクエスト/レスポンスログを添えてお問い合わせください。