HTTP ステータスコードとエラー

エラーや特殊なケースへの対応に役立つように、B2C Commerce API (SCAPI) は HTTP ステータスコードとエラーメッセージを返します。

次の表に、HTTP ステータスコードと一般的なユースケースを示します。

HTTP ステータスコードユースケース
200 (OK)GET、PUT、または POST リクエストが正常に完了しました。
201 (Created)POST または PUT リクエストが新しいリソースまたはリレーションシップリソースを正常に作成しました。
204 (No Content)リクエストは正常に完了し、返されるコンテンツはありません。
207 (Multi-Status)リクエストは正常に完了し、サブ操作ごとに複数のステータス結果が返されました。たとえば、バッチレスポンスや部分レスポンスなどです。
HTTP ステータスコードユースケース
400 (Bad Request)リクエストに無効な情報が含まれています。たとえば、不正な形式のパラメーター、不正な形式のヘッダー値、不正な形式のボディなどです。
401 (Unauthorized)リクエストは、処理を許可されていません。
403 (Forbidden)リクエストはサーバーによって拒否されました。
404 (Not Found)リクエストされたリソースは存在しません。
405 (Method Not Allowed)リソースは、指定された HTTP メソッドをサポートしていません。
409 (Conflict)リクエストは、リソースの現在の状態との競合により完了できませんでした。
412 (Precondition Failed)PATCH リクエストで、古い最終既知のベースポイントが指定されました。これは、リソースがサーバー上で変更されており、同時実行中の別のリクエストによって変更された可能性があることを意味します。
415 (Unsupported Media Type)"format" リクエストパラメーター (または Accept ヘッダー) で指定されたメディアタイプはサポートされていません。
500 (Internal Server Error)サーバー上の予期しない状態により、リクエストを処理できません。

すべての B2C Commerce API には、どの API からも返される可能性のある共通のエラーメッセージがいくつかあります。 API レベルのドキュメントでは、API 固有のエラーメッセージに重点を置いています。

タイプ詳細
missing-query-parameter必須クエリパラメータが不足しています: '{missingParams}'
undefined-query-parameterクエリパラメーター '{undefinedParam}' は、この API では定義されていません。
value-constraint-violationパラメーター '{parameterName}' の値が、API 制約 '{constraintName}' に違反しています。
constraint-violation'{parameterName}' の値が制約に違反しています。想定値は '(x..y)' の範囲内です。
adhoc-logging-not-supportedこの API は、sdfc-log-level や sfdc-verbose headers をサポートしていません。これらを削除してください。
incorrect-preflightプリフライトリクエストの形式が不正であるか、不完全です: {detail}
タイプ詳細
unauthorized認証されていないリクエストです。
タイプ詳細
forbiddenリクエストされたリソースへのアクセスは禁止されています。
タイプ詳細
resource-not-foundリクエストされたリソースが見つかりませんでした。
organization-not-foundorganizationId '{organizationId}' に対応する組織が見つかりませんでした。
タイプ詳細追加情報
method-not-allowedリクエストされたリソースでは、このリクエストメソッドは許可されていません。
custom-apis-optionsカスタム API では、OPTIONS メソッドはサポートされていません。カスタム API のトラブルシューティング
タイプ詳細
request-uri-too-longリクエスト URL の長さの上限を超えています。
タイプ詳細追加情報
payload-too-largeリクエストペイロードまたはリクエストヘッダーのサイズが大きすぎるため、処理できません。リクエストとレスポンスの制約
タイプ詳細
missing-content-typeContent-Type ヘッダーがありません。想定値: '{expected}'
unsupported-content-typeContent-Type ヘッダー内のメディアタイプはサポートされていません。想定値: '{expected}'
unsupported-content-typeContent-Type ヘッダー内の文字セットはサポートされていません。想定値: '{expected}'
タイプ詳細
too-many-requests短時間に、アドホックロギング付きのリクエストを実行しすぎています。
タイプ詳細
internal-server-error内部サーバーエラー
タイプ詳細追加情報
service-unavailable現時点ではリクエストを処理できません。
service-unavailableサーバー側でのリソース消費が高いため、リクエストはスロットリングされました。詳細については、'sfdc_load' ヘッダーを参照してください。
system-under-maintenanceシステムが現在メンテナンス中のため、リクエストを処理できませんでした。メンテナンスレスポンスコード
site-under-maintenanceサイトが現在メンテナンス中のため、リクエストを処理できませんでした。メンテナンスレスポンスコード

SCAPI リクエストへのレスポンスに時間がかかりすぎる場合は、HTTP 504 ステータスコードが返されます。

タイプ詳細追加情報
request-timeoutシステムがタイムアウトしきい値内にリクエストを処理できませんでした。リクエストタイムアウトのトラブルシューティング

Shopper API と Custom API は 10 秒以内にレスポンスする必要があり、SCAPI Admin API リクエストは 60 秒以内にレスポンスする必要があります。SCAPI リクエストへのレスポンスがタイムアウトしきい値を超えると、HTTP 504 ステータスコードが返されます。

タイムアウトの問題が発生した場合は、フック実装の最適化を検討してください。

SLAS や Omnichannel Inventory (OCI) などの一部の API ファミリーには、ゲートウェイのタイムアウトがありません。

ステータスコードが 400 以上の場合、API は RFC 7807 Problem Details 形式に従ったエラーレスポンスを返します。例:

エラーレスポンスには、次のプロパティが含まれます。

  • title: 問題タイプに関する、人が読んで理解できる簡潔な要約。これは、ローカライズを目的とする場合を除き、問題が発生するたびに変わることはありません。
  • type: 問題タイプを識別する URI 参照。参照先を解決すると、その問題タイプに関する人が読んで理解できるドキュメントが提供される必要があります。このメンバーが存在しない場合、その値は "about:blank" と見なされます。
  • detail: この問題の発生事象に固有の、人が読んで理解できる説明。
  • instance: この問題の特定の発生事象を識別する URI 参照。参照先を解決した場合に追加情報が得られることもあれば、得られないこともあります。

アプリケーションで SCAPI エラーを処理する場合は、次のベストプラクティスに従ってください。

  1. 常に、HTTP レスポンスメッセージではなく、HTTP レスポンスのステータスコードに基づいて実装してください。
  2. さまざまなエラーシナリオをプログラムで処理するには、type フィールドの最後のセグメントを使用してください。
  3. 503 エラーは、通常、一時的なサーバー側の問題であるため、再試行ロジックの実装を検討してください。
  4. 400 エラーを最小限に抑えるために、クライアント側で入力を検証してください。
  5. 根本原因が不明な 500 エラーが発生した場合は、次の点を確認してください。
    • カスタマイズヘッダー (sfdc_customization_error) を確認してください。値が「1」の場合、フックの実行中にエラーが発生しています。
    • 根本原因を突き止めたり、サポートケースを開いたりするために、sfdc_correlation_id レスポンスヘッダーの値をコピーしてください。