イントロダクション
この記事は、Microsoft Fabric REST API によって返される一般的なエラーを理解し、トラブルシューティングするのに役立ちます。 サービスで使用される標準エラー形式について説明し、最も頻繁に発生する HTTP 状態コードを解決するためのガイダンスを提供します。
Microsoft Fabric エラー応答について
Microsoft Fabric REST API への要求の処理中にエラーが発生すると、サービスは応答本文で標準の ErrorResponse オブジェクトを返します。
トラブルシューティングを行うときは、要求を一意に識別し、Microsoft サポートに問い合わせる際に必要であるため、常に requestIdをキャプチャしてログに記録します。 要求 ID は、応答本文と応答ヘッダーの両方で使用できます。
重要
errorCode値は安定しており、コントラクトベースです。- 人間が判読できる
messageテキストは、時間の経過と伴って変化する可能性があるため、プログラムで解析しないでください。
ErrorResponse スキーマ
| 名前 | タイプ | Description |
|---|---|---|
errorCode |
string |
エラー条件の安定した識別子。 エラー処理ロジックを実装する場合は、この値を使用します。 |
message |
string |
人が判読できるエラーの説明。 |
moreDetails |
ErrorResponseDetails[] |
省略可能な追加エラーの詳細一覧。 |
relatedResource |
ErrorRelatedResource |
エラーに関連付けられているリソースに関する情報 (該当する場合)。 |
requestId |
string |
失敗した要求の一意識別番号。 Microsoft サポートに問い合わせる場合は、この値を含めます。 |
ErrorResponseDetails スキーマ
複雑なエラー シナリオに対して追加のコンテキストを提供します。
| 名前 | タイプ | Description |
|---|---|---|
errorCode |
string |
特定のエラーの詳細を記述する安定した識別子。 |
message |
string |
エラーの詳細を人間が判読できる説明。 |
relatedResource |
ErrorRelatedResource |
この特定のエラーの詳細に関連付けられているリソース。 |
ErrorRelatedResource スキーマ
エラーに関係するリソースを識別します。
| 名前 | タイプ | Description |
|---|---|---|
resourceId |
string |
エラーに関係するリソースの ID。 |
resourceType |
string |
リソースの種類 (ワークスペース、項目、容量など)。 |
一般的な HTTP エラー シナリオ
次のセクションでは、Microsoft Fabric REST API によって返される一般的な HTTP 状態コードと、一般的な根本原因と推奨される解決策について説明します。
API から 401 が返される – 未承認
401 応答は、認証またはアクセス トークンの検証中に要求が失敗したことを示します。
一般的な根本原因
| エラー コード | Description | 解決策 |
|---|---|---|
TokenExpired |
アクセス トークンの有効期限が切れています。 | 新しいアクセス トークンを取得し、要求を再試行します。 |
InsufficientScopes |
アクセス トークンには、必要なスコープは含まれません。 | API 仕様に記載されている必要なスコープを要求するようにアプリケーションを更新するか、Microsoft Entraアプリケーションの登録を更新します。 |
API から 403 が返される – 禁止
403 応答は、呼び出し元が認証されているが、ターゲット リソースに対して要求された操作を実行するための十分なアクセス許可がないことを示します。
一般的な根本原因
| エラー コード | Description | 解決策 |
|---|---|---|
InsufficientPrivileges |
呼び出し元には、リソースにアクセスするために必要なアクセス許可がありません。 | ワークスペースまたはリソース管理者に、呼び出し元のユーザーまたはサービス プリンシパルに十分なアクセス許可を付与するよう依頼します。 |
API から 404 が返される - 見つかりません
404 応答は、要求されたリソースまたは参照されているリソースが存在しないか、呼び出し元からアクセスできなかったことを示します。
注
個々の API では、追加の API 固有のエラー コードを定義できます。 権限のある詳細については、常に API 仕様を参照してください。
一般的な根本原因
| エラー コード | Description | 解決策 |
|---|---|---|
WorkspaceNotFound |
指定したワークスペースが見つかりませんでした。 | 正しいワークスペース オブジェクト ID が指定されたことを確認します。 |
EntityNotFound |
要求されたリソースが見つかりませんでした。 | 正しいリソース ID が指定されたことを確認します。 不足しているエンティティは、エラー応答の relatedResource フィールドで識別されます。 |
API から 429 が返される – 要求が多すぎます
429 レスポンスは、リクエストがスロットルされたことを示します。 Microsoft Fabricは、それぞれ応答本文で異なるerrorCodeによって識別される 2 つの異なる理由で、429 状態コードを返します。
一般的な根本原因
| エラー コード | Description | 解決策 |
|---|---|---|
RequestBlocked |
要求レートがサービスの調整制限を超えました。 | 再試行する前に、 Retry-After ヘッダーで指定された期間待機します。
アプリケーションでのレート制限の処理に関する説明を参照してください。 |
CapacityLimitExceeded |
お使いの容量で消費されたコンピューティング (容量ユニット) が、購入した Fabric SKU の上限を超えました。 | 後で要求を再試行してください。 「容量のスロットリングへの対処」を参照してください。 |
レート制限 (RequestBlocked)
RequestBlocked エラーは、要求レートがサービスの調整制限を超えたことを示します。
- 呼び出し元 ID ごとにスロットリングが適用されます。
- レート制限は通常、1 分間のウィンドウで評価されます。
再試行のタイミング情報
レート制限が発生した場合、再試行情報は次の 2 つの場所で提供されます。
応答本文 (
message)
例:
"Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"Retry-AfterHTTP 応答ヘッダー
クライアントが再試行するまでに待機する必要がある秒数を指定します。
再試行ロジックを実装するときは、常に Retry-After ヘッダーを優先します。
アプリケーションでレート制限を処理する
アプリケーションでは次の必要があります。
- HTTP 429 応答を検出します。
-
Retry-Afterヘッダーを解析して順守する。 - 高負荷シナリオにおいて、指数バックオフにジッターを加えた境界付き再試行ポリシーを適用します。
- 無限の再試行ループを避けます。
レート制限の可能性を減らす
- 使用可能な場合は、一括操作とバッチ操作を使用します。
- 単一リソース要求を繰り返すよりも、リスト API を優先します。
- 頻繁にアクセスされるデータ、特に変更頻度の低いメタデータをキャッシュします。
- 時間の経過と同時に要求を均等に分散することで、トラフィックバーストを回避します。
容量制限を超えました (CapacityLimitExceeded)
CapacityLimitExceeded エラーは、お使いの容量で消費されたコンピューティング リソース (容量ユニット) が、購入した Fabric SKU の制限を超えたことを示します。 レート制限とは異なり、この調整は、特定の呼び出し元が行う API 呼び出しの数によって発生することはありません。これは、容量上のすべてのワークロードで消費された全体的なコンピューティングを反映します。
応答本文の例:
"Your organization's Fabric compute capacity has exceeded its limits. Try again later."
容量スロットリングへの対処
このスロットリングは、個別のリクエスト レートではなく、capacity 全体で消費されるコンピューティング リソースに依存するため、Retry-After ヘッダーは適用されません。また、capacity のコンピューティング使用量が上限内に戻るまでは、すぐに再試行しても成功する可能性は低いです。 アプリケーションでは次の必要があります。
- 指数バックオフがある有界再試行ポリシーを使用して、後で要求を再試行します。
- エラーが解決しない場合は、Fabric容量のスケールアップまたはスケールアウトを検討してください。
容量ユニット、SKU、および Fabric 容量がどのように消費されるかの詳細については、容量サイズを計画する を参照してください。
概要
Microsoft Fabric REST API との信頼性の高い統合を構築するには、堅牢なエラー処理と効率的な要求パターンが必要です。 エラー応答を理解し、調整シグナルを受け入れ、要求パターンを最適化することで、回復性のあるアプリケーションを構築できます。
関連コンテンツ
その他の質問やコミュニティ ガイダンスについては、Microsoft Fabric コミュニティを参照してください