Microsoft Graph のエラー応答とリソースの種類
Microsoft Graph のエラーは、標準の HTTP 状態コードと JSON エラー応答オブジェクトを使用して返されます。
HTTP 状態コード
次の表は、返される可能性のある HTTP ステータス コードの一覧とその説明を示します。
| 状態コード | ステータス メッセージ | 説明 |
|---|---|---|
| 400 | 要求が正しくありません (Bad Request) | 形式が正しくないか正しくないため、要求を処理できません。 |
| 401 | 権限がありません (Unauthorized) | リソースの必要な認証情報が見つからないか、無効です。 |
| 402 | 支払いが必要 | API の 支払い要件 が満たされていません。 |
| 403 | 禁止されています (Forbidden) | 要求されたリソースへのアクセスが拒否されました。 ユーザーが十分なアクセス許可を持っていないか、必要なライセンスを持っていない可能性があります。 大事な： 条件付きアクセス ポリシーがリソースに適用されている場合は、 HTTP 403; Forbidden error=insufficient_claims メッセージが返される可能性があります。 Microsoft Graph と条件付きアクセスの詳細については、「条件付きアクセスをMicrosoft Entraするための開発者ガイダンス」を参照してください。 |
| 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 | ゲートウェイ タイムアウト | サーバーは、プロキシとして機能しているときに、要求を完了するためにアクセスするために必要なアップストリーム サーバーからタイムリーな応答を受け取りませんでした。 |
| 507 | 記憶域の不足 (Insufficient Storage) | 記憶域の最大クォータに達しました。 |
| 509 | 帯域幅の上限を超えました (Bandwidth Limit Exceeded) | 帯域幅の上限を超えたため、アプリケーションが調整されました。 さらに時間が経過すると、アプリは要求を再試行できます。 |
エラー応答は、エラーという名前の 1 つのプロパティを含む 1 つの JSON オブジェクトです。 このオブジェクトには、すべてのエラーの詳細が含まれます。 HTTP 状態コードの代わりに、またはこれに加えて、ここに返される情報を使用することができます。 完全な JSON エラー本体の例を以下に示します。
{
"error": {
"code": "badRequest",
"message": "Uploaded fragment overlaps with existing data.",
"innerError": {
"code": "invalidRange",
"request-id": "request-id",
"date": "date-time"
}
}
}
エラー リソースの種類
要求の処理中にエラーが発生するたびに、エラー リソースが返されます。
エラー応答は、 Microsoft REST API ガイドラインの定義に従います。
JSON 表記
エラー リソースは、1 つのリソースで構成されます。
{
"error": {
"code": "string",
"message": "string",
"innererror": {
"code": "string"
},
"details": []
}
}
| プロパティ名 | 値 | 説明 |
|---|---|---|
| code | string | 発生したエラーのエラー コード文字列 |
| メッセージ | string | 発生したエラーに関する開発者向けメッセージ。 これはユーザーに直接表示しないでください。 |
| innererror | エラー オブジェクト | 省略可能。 最上位のエラーよりも具体的な可能性がある追加のエラー オブジェクト。 |
| details | error object | 省略可能。 要求の処理中に発生した複数のエラーの内訳を提供する可能性がある追加のエラー オブジェクトの一覧。 |
プロパティ
コード プロパティには、コード内で依存関係を取得できる、コンピューターが読み取り可能な値が含まれています。
innererror オブジェクトには、追加のより具体的なエラー コード プロパティを含む、より多くの innererror オブジェクトが再帰的に含まれる場合があります。 エラーを処理する場合、アプリは使用可能なすべての入れ子になったエラー コードをループし、理解できる最も詳細なエラー コードを使用する必要があります。
message プロパティは、エラー条件を記述する人間が判読できる値です。 コード内のこの値の内容に依存しないでください。
ルートの message プロパティには、開発者が読み取るためのエラー メッセージが含まれています。 エラー メッセージはローカライズされず、ユーザーに直接表示されるべきではありません。 エラーを処理する場合、コードは メッセージ プロパティの値に依存しないようにする必要があります。これは、いつでも変更でき、多くの場合、失敗した要求に固有の動的な情報が含まれているためです。 コード プロパティで返されるエラー コードに対してのみ コードを記述 する必要があります。
details プロパティは、最上位のエラー オブジェクトと同じ JSON 形式のエラー オブジェクトの省略可能な配列です。 一括操作やバッチ操作など、複数の操作で構成される要求の場合は、操作ごとに独立したエラーを返す必要がある場合があります。 この場合、 詳細 リストにこれらの個々のエラーが入力されます。