エラー コードとエラー処理 | Graph API の概念

  • [アーティクル]

適用対象: Graph API | Azure Active Directory

Azure Active Directory (AD) Graph API を使用するクライアント アプリケーションでは、さまざまな状況に可能な限り適切に対応し、顧客にとって最善となるユーザー エクスペリエンスを実現するため、エラー処理ロジックを実装する必要があります。 このトピックでは、Azure AD Graph API で発生するエラーの種類について説明し、その対処方法の一般的指針を示します。

重要

Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。現在は Microsoft Graph を中心にして開発が進められており、Azure AD Graph API の今後の機能強化は予定されていません。Azure AD Graph API の使用が適切である場合もありますが、非常にまれです。詳細については、Office Dev Center の Microsoft Graph または Azure AD Graph ブログの記事をご覧ください。

Graph API エラーの処理

エラーの種類

Graph API に発生するエラーは、以下のカテゴリに分けることができます。

  • クライアント エラー。 クライアント エラーは、HTTP ステータス コードの 400 番台に相当します。 これには、無効な値、オブジェクトに必要なプロパティまたはプロパティの値の不足、存在しないリソースに対するアクセスの試行、読み取り専用プロパティを更新しようとする操作、必要な認証トークンの不足などがあります。 この種のエラーを解決するには、リクエストの再試行に先立って原因となった問題を修正する必要があります。
  • サーバー エラー。 サーバー エラーは、ディレクトリの一時的な障害など、HTTP ステータス コードの 500 番台に相当するものです。 この種のエラーはほとんどが一時的なものであり、リクエストを再試行することによって解決が可能です。
  • ネットワーク/プロトコル エラー。 リクエストの送信時や応答の受信時には、ホスト名の解決エラー、処理完了前の接続終了、SSL ネゴシエーション エラーなど、ネットワーク関連のさまざまなエラーが発生する可能性があります。 この種のエラーはほとんどが、再試行によって解決するものではありません。根底にある問題を解決する必要があります。 ただし、ホスト名の解決エラーやタイムアウトなど、一部のエラーについてはリクエストを再試行することによって解決することがあります。

エラー メッセージの構造

Graph API のエラーには、HTTP ステータス コード、メッセージ、および値から成る本文があります。 エラー処理のロジックでは、エラー本文のプロパティを使用します。

注: 一部の HTTP 応答では、コード/メッセージ/値の形式の応答本文がないことがあります。これは、リクエストがプロキシおよびゲートウェイのサービスによりルーティングされていることによるものです。 既定のロジックは、HTTP ステータス コードのみに基づいてエラーを処理できるものにしてください。

以下の例は、HTTP 400 Request_BadRequest エラーの例です。

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

エラー メッセージの本文には、code、message、および values のプロパティがあります。

  • code: コードに応じて分岐するようなエラー処理ロジックを設計します。

    "code" : "Request_BadRequest"

  • message: 人間が読むことができるエラー メッセージを表す言語と値の組み合わせです。 内容は、value フィールドにあります。 以下の例では、mailNickname プロパティに値が存在しないためにリクエストがエラーとなっています。

    "message" : {
     "lang" : "en",
     "value" : "A value is required for property 'mailNickname' of resource 'Group'."
}

  • Values: エラーの性質に関する詳細を示すための名前と値のペアの集合です。 以下の例に値は含まれていません。

    "values" : null

エラー コード リファレンス

HTTP エラー コード

次の表に、Graph API のエラー コード、エラー メッセージ、およびエラーを修正するときに検討すべきアクションを一覧します。

一般に、HTTP 500 番台のエラーは、徐々に長くなる時間間隔にわたって分布し ("バックオフ間隔のある再試行")、ランダムな分布係数を持つ再試行に応答します。 400 番台のエラーは再試行する前に解決する必要がある問題を示しています。

HTTP ステータス コード エラー コード エラー メッセージ 説明
400 Directory_ResultSizeLimitExceeded 結果のサイズの制限を超えました 要求が関連付けられている結果が多すぎるため、要求を処理できません。 このエラーはめったに発生しません。
400 Request_BadRequest 正しくない要求です。 再試行前に要求を修正してください。 無効なプロパティ値やサポートされていないクエリの引数など、要求に含まれるエラーを示します。 再試行する前に、要求を修正してください。
400 Request_UnsupportedQuery GET 要求はサポートされていません。 要求パラメーターを修正し、もう一度実行してください。
401 Authentication_ExpiredToken アクセス トークンの有効期限が切れています。 要求を送信する前にトークンを更新してください。 アクセス トークンの有効期限が切れています。 トークンを更新し、再実行してください。
401 Authentication_MissingOrMalformed アクセス トークンがないか、または正しくありません。 承認ヘッダーの access_token 値がないか、正しくありません。 この値は必須です。 認証トークンの値を使用します。
401 Authorization_IdentityDisabled 呼び出し元アプリケーションのプリンシパルが無効になっています。 アクセス トークンで指定されたプリンシパルがディレクトリにありますが、無効になっています。 ディレクトリ内のアカウントを再度有効にし、もう一度やり直してください。
401 Authorization_IdentityNotFound 呼び出し元アプリケーションの ID を確立できませんでした。 アクセス トークンで指定されたプリンシパルが、ディレクトリ内に見つかりませんでした。 これは、トークンが古いとき、プリンシパルがディレクトリから削除されたとき、またはディレクトリの同期が遅れているときに発生する可能性があります。
403 Authentication_Unauthorized 許可されていない要求です。 トークンに、無効な要求またはサポートされていない要求が含まれています。 要求トークンを再度取得し、要求を再試行してください。
403 Authorization_RequestDenied 指定された資格情報に、この要求を行うための十分な特権がありません。 十分な特権がないために、要求が拒否されます。 たとえば、管理者以外のプリンシパルにリソースを削除する権限がありません。
403 Directory_QuotaExceeded {tenantName} のディレクトリ オブジェクトのクォータ制限を超えました。 クォータ制限を増やすか、オブジェクトを削除して使用済みのクォータを減らすように、管理者に依頼してください。 ディレクトリ クォータを超えました。 テナントにあるオブジェクトが多すぎるか、オブジェクトが持つ値が多すぎます。 これは、プリンシパル用に作成されるオブジェクトが多すぎるときにも発生します。 テナントまたはプリンシパルの最大許容オブジェクト数を増やすか、作成/更新要求に含まれる値の数を減らしてください。
404 Request_ResourceNotFound リソース {resource} が存在しないか、クエリ対象の参照プロパティ オブジェクトの 1 つがありません。 URI で識別されたリソースが存在しません。 値を修正し、要求を再試行してください。
409 Request_MultipleObjectsWithSameKeyValue 予期されていた結果は 1 つのリソースでしたが、複数のリソースが見つかりました。競合を解決するためにオブジェクトを更新してください。 このエラーは、同じキー値を持つ 2 つ以上のオブジェクトがある場合に発生することがあります。たとえば、同じ UserPrincipalName のユーザーが 2 人いる場合です。
429 要求が多すぎます。 要求に対してスロットルが発生している場合に、このエラーが発生します。応答ヘッダーの Retry-After 値で、推奨される待機時間が返されます。推奨される秒数を待機した後に、要求を再試行してください。
500 Service_InternalServerError 内部サーバー エラーが発生しました。 要求の処理中の内部サーバー エラーです。
502 [All] “...サービスを利用できません..." ゲートウェイまたはプロキシとして動作しているサーバーで、要求の処理中に別のサーバーからのエラーが発生しました。 数分待ってから、要求を再試行してください。
503 Request_ThrottledTemporarily 要求は一時的に調整されます。 {0} 秒後に再試行してください。 トークンの要求レートが、サービスが管理できる上限を超えました。 数分待ち、バックオフ間隔を大きくして要求を再試行してください。 再試行の間の遅延を増やすと、要求が成功し、バックログが除去される可能性が高くなります。
Authentication_Unknown 内部サーバー エラーです。 このエラー コードは、他のエラー コードが適用されない場合に使用されます。
Authentication_UnsupportedTokenType 提示されたトークンの型は処理されません。 ベアラー トークンだけがサポートされます。 トークンの型がサポートされていません。 要求を再試行する前に、トークンの型を修正してください。
Directory_BindingRedirection テナント情報をローカルで入手できません。 次の URL を使用して情報を入手してください。 テナントのパーティションがデータセンターで入手できない場合、クライアントは応答で返される URL に接続する必要があります。
Directory_BindingRedirectionInternalServerError テナント情報をローカルで入手できません。 最も近いデータセンターのエンドポイントの設定中に、サーバーで内部エラーが発生しました。 バインド リダイレクト例外が発生したとき、サービスの最も近いデータセンターのエンドポイントの一覧が設定されます。 このエラーは、一覧を設定するときの例外を示しています。 クエリを再試行してください。
Directory_CompanyNotFound ディレクトリから会社情報を読み取ることができません。 ディレクトリ サービスから会社情報を読み込み中に、エラーが発生しました。
Directory_ReplicaUnavailable 優先されるレプリカを使用できません。 レプリカ セッション キー ヘッダーなしで再試行してください。 x-ms-replica-session-key ヘッダーを省略し、再試行してください。
Headers_DataContractVersionMissing データ コントラクト バージョン ヘッダーがありません。 要求に x-ms-dirapi-data-contract-version を含めてください。 要求にクライアント コントラクト バージョンがありません。
Headers_HeaderNotSupported 現在、ヘッダー {0} はサポートされていません。 要求に、サポートされていない HTTP ヘッダーが含まれています。 ヘッダーを変更し、要求を再試行してください。
Request_InvalidReplicaSessionKey 指定されたレプリカ セッション キーが無効です。 レプリカ セッション キーを修正し、要求を再試行してください。
Request_ThrottledPermanently 要求は永続的に調整されます。 問題に対処するためにサポートに電話してください。 テナントは、何度もトークンの要求レートの制限を超えました。 このテナントからの要求は、サービスが再ネゴシエートされるまで拒否されます。 支援が必要な場合は、Microsoft サポートに連絡してください。

その他のリソース