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 プロパティを更新できません。
resyncApplyDifferences 再同期が必要です。最後に同期したときに、サービスをローカル変更に対して最新の状態にしたことが確実な場合、すべてのローカル項目をサーバーのバージョンと置き換えます (削除を含む)。サーバーが把握していないすべてのローカル変更をアップロードします。
resyncRequired 再同期が必要です。
resyncUploadDifferences 再同期が必要です。サービスが返さないすべてのローカル アイテムをアップロードして、サーバーのバージョンと異なるすべてのファイルをアップロードします (どちらがより最新の状態であるかわからない場合は、両方のコピーを保持する)。
serviceNotAvailable サーバーが現在の要求を処理できません。
serviceReadOnly リソースが一時的に読み取り専用になっています。
throttledRequest 要求数が多すぎます。
tooManyResultsRequested 要求された結果が多すぎます。
tooManyTermsInQuery クエリ内のアイテムが多すぎます。
totalAffectedItemCountExceeded 影響を受けるアイテム数がしきい値を超えているため、操作は許可されません。
truncationNotAllowed データの切り捨ては許可されていません。
uploadSessionFailed アップロード セッションが失敗しました。
uploadSessionIncomplete アップロード セッションが完了していません。
uploadSessionNotFound アップロード セッションが見つかりません。
virusSuspicious このドキュメントは疑わしいドキュメントであり、ウイルスを含んでいる可能性があります。
zeroOrFewerResultsRequested ゼロ個以下の結果が要求されました。