Microsoft Graph のエラー応答とリソースの種類

Microsoft Graph のエラーは、標準の HTTP 状態コード、および JSON エラー応答オブジェクトを使用して返されます。

HTTP 状態コード

次の表は、返される可能性のある HTTP ステータス コードの一覧とその説明を示します。

状態コード	ステータス メッセージ	説明
400	要求が正しくありません (Bad Request)	形式が正しくない、または無効なため、要求を処理できません。
401	権限がありません (Unauthorized)	リソースの必要な認証情報が見つからないか、無効です。
403	禁止されています	要求されたリソースへのアクセスが拒否されました。ユーザーに十分なアクセス許可がない可能性があります。 重要: 条件付きアクセス ポリシーがリソースに適用される場合、HTTP 403; Forbidden error=insufficent_claims が返される場合があります。 Microsoft Graph と条件付きアクセスの詳細は、「Azure Active Directory の条件付きアクセスについての開発者ガイド」を参照してください。
404	見つかりません (Not Found)	要求されたリソースは存在しません。
405	メソッドが許可されていません (Method Not Allowed)	要求の HTTP メソッドはリソースで許可されていません。
406	許容されません (Not Acceptable)	このサービスでは、Accept ヘッダーで要求された形式をサポートしていません。
409	競合 (Conflict)	現在の状態が要求に必要なものと競合しています。たとえば、指定された親フォルダーが存在しない可能性があります。
410	使用されていないリソース (Gone)	要求されたリソースはサーバーで使用できなくなっています。
411	長さが必要 (Length Required)	要求に Content-Length ヘッダーが必要です。
412	必須条件に失敗しました (Precondition Failed)	要求で提供されている必須条件 (If-match ヘッダーなど) がリソースの現在の状態と一致しません。
413	要求エンティティが大きすぎます (Request Entity Too Large)	要求サイズが上限を超えています。
415	メディアの種類がサポートされていません (Unsupported Media Type)	要求のコンテンツの種類がサービスによってサポートされていない形式です。
416	要求された範囲が満たされません (Requested Range Not Satisfiable)	指定したバイト範囲が正しくない、または利用できません。
422	処理できないエンティティです (Unprocessable Entity)	意味的に正しくないため、要求を処理できません。
423	ロックされています	アクセスしているリソースがロックされています。
429	要求数が多すぎます (Too Many Requests)	クライアント アプリケーションは調整されており、一定の時間が経過するまで要求を繰り返しません。
500	内部サーバー エラー (Internal Server Error)	要求の処理中に内部サーバー エラーが発生しました。
501	実装されていません (Not Implemented)	要求された機能は実装されていません。
503	サービスは利用できません	メンテナンスまたは過負荷のため、このサービスは一時的に利用できません。後で要求を繰り返すことができます。期間については、Retry-After ヘッダーで指定されている可能性があります。
504	ゲートウェイ タイムアウト	プロキシとして動作しているサーバーが、要求を完了しようとするときにアクセスが必要なアップストリーム サーバーからの応答を時間内に受信しませんでした。503 と同時に発生する場合があります。
507	記憶域の不足 (Insufficient Storage)	記憶域の最大クォータに達しました。
509	帯域幅の上限を超えました (Bandwidth Limit Exceeded)	帯域幅の上限を超えたため、アプリケーションが調整されました。さらに時間が経過すると、アプリは要求を再試行できます。

エラー応答は、エラー という名前の 1 つのプロパティを含む 1 つの JSON オブジェクトです。このオブジェクトには、すべてのエラーの詳細が含まれます。HTTP 状態コードの代わりに、またはこれに加えて、ここに返される情報を使用することができます。完全な JSON エラー本体の例を以下に示します。

{
  "error": {
    "code": "invalidRange",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "requestId": "request-id",
      "date": "date-time"
    }
  }
}

エラー リソースの種類

要求の処理中にエラーが発生するたびに、エラー リソースが返されます。

エラー応答は、エラー応答に対する OData v4 仕様の定義に従います。

JSON 表記

エラー リソースは、これらのリソースで構成されます。

{
  "error": { "@odata.type": "odata.error" }  
}

odata.error のリソースの種類

エラー内で、応答は次のプロパティを含むエラー リソースです。

{
  "code": "string",
  "message": "string",
  "innererror": { "@odata.type": "odata.error" }
}

プロパティ名	値	説明
code	string	発生したエラーのエラー コード文字列
メッセージ	string	発生したエラーに関する開発者用メッセージ。これはユーザーには直接表示されません。
innererror	error object	省略可能。最上位レベルのエラーよりも詳細である可能性のある追加のエラー オブジェクト。

コードのプロパティ

code プロパティには次のいずれかの値が含まれます。アプリは、これらのエラーのいずれかを処理するように準備する必要があります。

コード	説明
accessDenied	呼び出し元にアクションを実行するアクセス許可がありません。
activityLimitReached	アプリまたはユーザーが調整されました。
extensionError	メールボックスがオンプレミスにあり、Exchange サーバーがフェデレーション Microsoft Graph 要求をサポートしていないか、アプリケーション ポリシー がアプリケーションによるメールボックスへのアクセスを禁止しています。
generalException	不明なエラーが発生しました。
invalidRange	指定したバイト範囲が正しくない、または利用できません。
invalidRequest	要求は形式が正しくないか、無効です。
itemNotFound	リソースが見つかりませんでした。
malwareDetected	要求されたリソースでマルウェアが検出されました。
nameAlreadyExists	指定されたアイテム名は既に存在します。
notAllowed	このアクションはシステムで許容されません。
notSupported	要求はシステムでサポートされていません。
resourceModified	呼び出し元による最後の読み取り以降に、更新されるリソースが変更されました。通常、eTag の不一致です。
resyncRequired	デルタ トークンは無効になりました。アプリが同期状態をリセットする必要があります。
serviceNotAvailable	サービスが利用できません。後で要求をもう一度お試しください。Retry-After ヘッダーがある可能性があります。
syncStateNotFound	同期状態の世代が見つかりません。 デルタトークンの期限が切れています。データをもう一度同期する必要があります。
quotaLimitReached	ユーザーがクォータ制限に達しました。
unauthenticated	呼び出し元が認証されていません。

innererror オブジェクトには、さらに詳細な追加のエラー コードを持つ別の複数の innererror オブジェクトが再帰的に含まれる可能性があります。エラーを処理する際に、アプリは使用可能なすべてのエラー コード間をループして、アプリが理解する最も詳細なコードを使用する必要があります。より詳細なコードの一部は、このページの下部に一覧表示されています。

エラー オブジェクトが予期したとおりのエラーであることを確認するには、innererror オブジェクト全体をループして、予期したエラー コードを検索する必要があります。次に例を示します。

public bool IsError(string expectedErrorCode)
{
    OneDriveInnerError errorCode = this.Error;
    while (null != errorCode)
    {
        if (errorCode.Code == expectedErrorCode)
            return true;
        errorCode = errorCode.InnerError;
    }
    return false;
}

エラーを正しく処理する方法を示す例については、「エラー コードの処理」を参照してください。

ルートにある message プロパティには、開発者が読み取ることを目的としたエラー メッセージが含まれます。 エラー メッセージはローカライズされておらず、直接ユーザーに表示すべきではありません。 エラーを処理する場合、コードはいつでも変更でき、多くの場合、失敗した要求に固有の動的な情報が含まれているため、message 値に基づいて分岐しないようにする必要があります。 code プロパティで返されるエラー コードに対してのみ、コードを記述する必要があります。

詳細なエラー コード

入れ子になった innererror オブジェクト内でアプリが検出する可能性のある他のエラーの一部を、以下に示します。アプリでこれらの処理を行うことは必須ではありませんが、処理することもできます。サービスでは常に新しいエラー コードが追加されたり、以前のコードが返されなくなったりすることがあります。そのため、基本のエラー コードをすべてのアプリが処理できることが重要です。

コード	説明
accessRestricted	アイテムの所有者に限定されたアクセス。
cannotSnapshotTree	一貫性のあるデルタ スナップショットを取得できませんでした。後でもう一度お試しください。
childItemCountExceeded	子アイテムの上限数に達しました。
entityTagDoesNotMatch	eTag が現在のアイテムの値と一致しません。
fragmentLengthMismatch	このフラグメントの宣言された合計サイズは、アップロード セッションのものとは異なります。
fragmentOutOfOrder	アップロードされたフラグメントが順不同です。
fragmentOverlap	アップロードされたフラグメントが既存のデータと重複しています。
invalidAcceptType	承諾の種類が正しくありません。
invalidParameterFormat	パラメーターの書式が正しくありません。
invalidPath	名前に使用できない文字が含まれています。
invalidQueryOption	クエリのオプションが正しくありません。
invalidStartIndex	開始インデックスが正しくありません。
lockMismatch	ロック トークンが既存のロックと一致しません。
lockNotFoundOrAlreadyExpired	現在、期限切れでないロックがアイテムにありません。
lockOwnerMismatch	ロック所有者の ID が提供された ID と一致しません。
malformedEntityTag	eTag ヘッダーの形式が正しくありません。eTag は、引用符で囲まれた文字列である必要があります。
maxDocumentCountExceeded	ドキュメントの上限数に達しました。
maxFileSizeExceeded	ファイル サイズの上限を超えました。
maxFolderCountExceeded	フォルダーの上限数に達しました。
maxFragmentLengthExceeded	ファイル サイズの上限を超えました。
maxItemCountExceeded	アイテムの上限数に達しました。
maxQueryLengthExceeded	クエリの長さの上限を超えました。
maxStreamSizeExceeded	ストリーム サイズの上限を超えました。
parameterIsTooLong	パラメーターの長さが上限を超えています。
parameterIsTooSmall	パラメーターの値が最小値未満です。
pathIsTooLong	パスの長さが上限を超えています。
pathTooDeep	フォルダー階層の深さの限度に達しました。
propertyNotUpdateable	プロパティを更新できません。
provisioningNotAllowed	要求にはアカウントのプロビジョニングが必要です。これは許可されていません。
resourceBeingProvisioned	要求されたリソースをプロビジョニングしています。
resyncApplyDifferences	再同期が必要です。最後に同期したときに、サービスをローカル変更に対して最新の状態にしたことが確実な場合、すべてのローカル項目をサーバーのバージョンと置き換えます (削除を含む)。サーバーが把握していないすべてのローカル変更をアップロードします。
resyncRequired	再同期が必要です。
resyncUploadDifferences	再同期が必要です。サービスが返さないすべてのローカル アイテムをアップロードして、サーバーのバージョンと異なるすべてのファイルをアップロードします (どちらがより最新の状態であるかわからない場合は、両方のコピーを保持する)。
serviceNotAvailable	サーバーが現在の要求を処理できません。
serviceReadOnly	リソースが一時的に読み取り専用になっています。
throttledRequest	要求数が多すぎます。
tooManyResultsRequested	要求された結果が多すぎます。
tooManyTermsInQuery	クエリ内のアイテムが多すぎます。
totalAffectedItemCountExceeded	影響を受けるアイテム数がしきい値を超えているため、操作は許可されません。
truncationNotAllowed	データの切り捨ては許可されていません。
uploadSessionFailed	アップロード セッションが失敗しました。
uploadSessionIncomplete	アップロード セッションが完了していません。
uploadSessionNotFound	アップロード セッションが見つかりません。
virusSuspicious	このドキュメントは疑わしいドキュメントであり、ウイルスを含んでいる可能性があります。
zeroOrFewerResultsRequested	ゼロ個以下の結果が要求されました。