Table of contents

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

Jimaco Brannian|最終更新日: 2016/09/07
|
1 投稿者

適用対象: Graph API | Azure Active Directory (AD)

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

重要

Azure AD Graph API の機能は、統合 API の Microsoft Graph からも使用できます。Microsoft Graph には、Outlook、OneDrive、OneNote、Planner、Office Grap など他の Microsoft サービスの API も含まれており、これらはすべて単一のアクセス トークンを使用して単一のエンドポイントからアクセスします。

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 状態コードエラー コードエラー メッセージ説明
400Directory_ExpiredPageToken指定したページのトークンの値は有効期限が切れており、要求に含めることはできません。
400Directory_ResultSizeLimitExceeded結果のサイズの制限を超えました要求が関連付けられている結果が多すぎるため、要求を処理できません。 このエラーはめったに発生しません。
400DomainVerificationCodeNotFound一致する確認コードを持つ TXT レコードが確認プロセスで検出できないため、ドメインの確認が失敗します。
400ObjectConflictこの会社の未確認のドメインにこのドメイン名が既に存在します。
400ObjectConflictこの会社の確認済みドメインにこのドメイン名が既に存在します。
400ObjectInUseユーザー、グループ、またはマルチテナント アプリケーションで現在参照されているドメインを削除できません。
400ObjectPendingDeletion削除が保留になっている既存のドメインを確認できません。
400ObjectPendingTakeoverテナント引き継ぎのプロセスでドメインを削除することができません。
400Request_BadRequest正しくない要求です。 再試行前に要求を修正してください。無効なプロパティ値やサポートされていないクエリの引数など、要求に含まれるエラーを示します。 再試行する前に、要求を修正してください。
400Request_DataContractVersionMissingデータ コントラクト バージョン パラメーターがありません。 すべての要求にクエリ パラメーターとして api-version を含めてください。
400Request_InvalidDataContractVersion指定した api-version は無効です。 値はサポートされているバージョンと正確に一致する必要があります。
400Request_InvalidRequestUrl要求 URL が無効でした。 要求は /tenantdomainname/Entity または /$metadata のようにする必要があります。 テナントのドメイン名は、確認済みまたは未確認のドメイン名かコンテキスト ID にすることができます。
400Request_UnsupportedQueryGET 要求はサポートされていません。 要求パラメーターを修正し、もう一度実行してください。
401Authentication_ExpiredTokenアクセス トークンの有効期限が切れています。 要求を送信する前にトークンを更新してください。アクセス トークンの有効期限が切れています。 トークンを更新し、再実行してください。
401Authentication_MissingOrMalformedアクセス トークンがないか、または正しくありません。承認ヘッダーの access_token 値がないか、正しくありません。 この値は必須です。 認証トークンの値を使用します。
401Authorization_IdentityDisabled呼び出し元アプリケーションのプリンシパルが無効になっています。アクセス トークンで指定されたプリンシパルがディレクトリにありますが、無効になっています。 ディレクトリ内のアカウントを再度有効にし、もう一度やり直してください。
401Authorization_IdentityNotFound呼び出し元アプリケーションの ID を確立できませんでした。アクセス トークンで指定されたプリンシパルが、ディレクトリ内に見つかりませんでした。 これは、トークンが古いとき、プリンシパルがディレクトリから削除されたとき、またはディレクトリの同期が遅れているときに発生する可能性があります。
403Authentication_Unauthorized許可されていない要求です。トークンに、無効な要求またはサポートされていない要求が含まれています。 要求トークンを再度取得し、要求を再試行してください。
403Authorization_RequestDenied指定された資格情報に、この要求を行うための十分な特権がありません。十分な特権がないために、要求が拒否されます。 たとえば、管理者以外のプリンシパルにリソースを削除する権限がありません。
403Directory_QuotaExceeded{tenantName} のディレクトリ オブジェクトのクォータ制限を超えました。 クォータ制限を増やすか、オブジェクトを削除して使用済みのクォータを減らすように、管理者に依頼してください。ディレクトリ クォータを超えました。 テナントにあるオブジェクトが多すぎるか、オブジェクトが持つ値が多すぎます。 これは、プリンシパル用に作成されるオブジェクトが多すぎるときにも発生します。 テナントまたはプリンシパルの最大許容オブジェクト数を増やすか、作成/更新要求に含まれる値の数を減らしてください。
404Directory_ObjectNotFoundディレクトリから会社情報を読み取ることができません。
404Request_ResourceNotFoundリソース {resource} が存在しないか、クエリ対象の参照プロパティ オブジェクトの 1 つがありません。URI で識別されたリソースが存在しません。 値を修正し、要求を再試行してください。
409Request_MultipleObjectsWithSameKeyValue予期されていた結果は 1 つのリソースでしたが、複数のリソースが見つかりました。 競合を解決するためにオブジェクトを更新してください。このエラーは、同じキー値を持つ 2 つ以上のオブジェクトがある場合に発生することがあります。たとえば、同じ UserPrincipalName のユーザーが 2 人いる場合です。
500Service_InternalServerError内部サーバー エラーが発生しました。要求の処理中の内部サーバー エラーです。
502[All]“...サービスを利用できません..."ゲートウェイまたはプロキシとして動作しているサーバーで、要求の処理中に別のサーバーからのエラーが発生しました。 数分待ってから、要求を再試行してください。
503Directory_ConcurrencyViolationテナントに同時実行要求が発生した場合のエラーです。 しばらくしてから、再試行してください。
503Request_ThrottledTemporarily要求は一時的に調整されます。 {0} 秒後に再試行してください。トークンの要求レートが、サービスが管理できる上限を超えました。 数分待ち、バックオフ間隔を大きくして要求を再試行してください。 再試行の間の遅延を増やすと、要求が成功し、バックログが除去される可能性が高くなります。
503DNS の確認中にエラーが発生しました (注: DNS が現在ダウンしているなど、さまざまな理由で発生することがあります)。
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 サポートに連絡してください。

その他のリソース

© 2017 Microsoft