Fehlercodes und Fehlerbehandlung | Graph-API-Konzepte

  • Artikel

Gilt für: Graph-API | Azure Active Directory (AD)

Für Clientanwendungen, die die Azure AD Graph-API verwenden, sollte eine Fehlerbehandlungslogik implementiert werden, um optimal auf verschiedene Umstände zu reagieren und ihren Benutzern ein bestmögliches Nutzungserlebnis zu bieten. Dieser Artikel behandelt die Fehler, die von der Azure AD Graph-API zurückgegeben werden, und bietet Hilfestellungen zu deren Behandlung.

Wichtig

Es wird dringend empfohlen, für den Zugriff auf Azure Active Directory-Ressourcen Microsoft Graph zu verwenden, nicht die Azure AD Graph-API. Wir konzentrieren unsere Entwicklungsarbeit auf Microsoft Graph, weitere Verbesserungen für die Azure AD Graph-API sind nicht geplant. Es gibt einige wenige Szenarien, in denen die Azure AD Graph-API möglicherweise noch geeignet ist. Weitere Informationen finden Sie im Office Dev Center im Blogbeitrag Microsoft Graph or the Azure AD Graph.

Behandeln von Graph-API-Fehlern

Fehlertypen

Graph-API-Fehler sind in die folgenden Kategorien unterteilt.

  • Clientfehler. Clientfehler werden durch HTTP-Statuscodes 4xx dargestellt. In diese Kategorie fallen Objekte mit ungültigen Werten, Objekte mit fehlenden Eigenschaften oder Eigenschaftswerten, Zugriffsversuche auf nicht existierende Ressourcen, Aktualisierungsversuche für schreibgeschützte Eigenschaften und Anforderungen ohne das benötigte Autorisierungstoken. Korrigieren Sie das zugrunde liegende Problem und senden Sie die Anforderung erneut, um diese Art von Fehlern zu beheben.
  • Serverfehler. Serverfehler werden durch HTTP-Statuscodes 5xx dargestellt, wie z. B. vorübergehende Verzeichnisfehler. Die meisten dieser Fehler sind vorübergehend und können durch eine Wiederholung der Anfrage behoben werden.
  • Netzwerk-/Protokollfehler. Bei Anforderung und Antwort kann eine Vielzahl netzwerkbedingter Fehler auftreten, wie z. B. Namensauflösungsfehler, vorzeitig geschlossene Verbindungen und SSL-Vermittlungsfehler. Die meisten dieser Fehler können nicht durch Wiederholungen behoben werden; stattdessen muss die zugrunde liegende Ursache korrigiert werden. Manche Fehler wie z. B. Namensauflösungsfehler oder Zeitüberschreitungen können jedoch durch eine Wiederholung der Anfrage behoben werden.

Struktur der Fehlermeldungen

Graph-API-Fehler haben einen formatierten Text, der aus einem HTTP-Statuscode, einer Nachricht und Werten besteht. Verwenden Sie in der Fehlerbehandlungslogik die Eigenschaften des Fehlertexts.

Hinweis: Nicht alle HTTP-Antworten enthalten den Text mit Code/Nachricht/Werten, da die Anforderung durch Proxy- und Gatewaydienste geleitet wird. Sie sollten daher auch eine Standardlogik implementieren, die Fehler allein anhand des HTTP-Statuscodes behandelt.

Es folgt ein Beispiel für einen HTTP 400 Request_BadRequest-Fehler.

 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
    }
 }

Jeder Meldungstext verfügt über die Eigenschaften „code“, „message“ und „values“.

  • code: Entwerfen Sie eine Fehlerbehandlungslogik, deren Verzweigungen auf Code basieren.

    "code" : "Request_BadRequest"

  • message: Ein Sprache-/Wert-Tupel, das eine lesbare Fehlermeldung darstellt. Der Inhalt befindet sich im value-Feld. Die Anforderung im folgenden Beispiel schlägt fehl, weil der Wert der mailNickname-Eigenschaft fehlt.

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

  • values: Eine Sammlung von Name-Wert-Paaren, die weitere Informationen über den Fehler enthalten. Im folgenden Beispiel sind keine Werte enthalten.

    "values" : null

Referenz zu Fehlercodes

HTTP-Fehlercodes

In der folgenden Tabelle sind Fehlercodes, Fehlermeldungen und Korrekturmaßnahmen aufgeführt.

Im Allgemeinen werden HTTP 500-Fehler bei Wiederholungen ausgegeben, insbesondere wenn diese über immer längere Zeitintervalle verteilt werden ("Wiederholung bei einem Backoffintervall") und wenn ein zufälliger Verteilungsfaktor vorliegt. 400er Fehler weisen auf ein Problem hin, das vor der Wiederholung behoben werden muss.

HTTP-Statuscode Fehlercode Fehlermeldung Details
400 Directory_ExpiredPageToken Der angegebene Seitentokenwert ist abgelaufen und kann nicht länger in Ihrer Anforderung verwendet werden.
400 Directory_ResultSizeLimitExceeded Größenbeschränkung des Resultsets wurde überschritten Die Anforderung kann nicht beantwortet werden, da ihr zu viele Ergebnisse zugeordnet ist. Dieser Fehler tritt nur sehr selten auf.
400 DomainVerificationCodeNotFound Fehler bei der Domänenüberprüfung, da bei der Überprüfung kein TXT-Eintrag mit übereinstimmendem Überprüfungscode gefunden wurde.
400 ObjectConflict Der Domänenname ist bereits in einer nicht überprüften Domäne in diesem Unternehmen vorhanden.
400 ObjectConflict Der Domänenname ist bereits in einer überprüften Domäne in diesem Unternehmen vorhanden.
400 ObjectInUse Die Domäne, die momentan von einem Benutzer, einer Gruppe oder einer Anwendung mit mehreren Mandanten referenziert wird, kann nicht gelöscht werden.
400 ObjectPendingDeletion Eine vorhandene Domäne, deren Löschvorgang aussteht, kann nicht überprüft werden.
400 ObjectPendingTakeover Eine Domäne, für die gerade eine Mandantenübernahme ausgeführt wird, kann nicht gelöscht werden.
400 Request_BadRequest Ungültige Anforderung. Korrigieren Sie die Anforderung, bevor Sie den Vorgang wiederholen. Weist auf einen Fehler in der Anforderung hin, z. B. ein ungültiger Eigenschaftswert oder ein nicht unterstütztes Abfrageargument. Korrigieren Sie die Anforderung, bevor Sie den Vorgang wiederholen.
400 Request_DataContractVersionMissing Der Parameter für die Datenvertragsversion fehlt. Schließen Sie „api-version“ als Abfrageparameter in sämtliche Ihrer Anforderungen ein.
400 Request_InvalidDataContractVersion Die angegebene „api-version“ ist ungültig. Der Wert muss mit einer unterstützten Version übereinstimmen.
400 Request_InvalidRequestUrl Die Anforderungs-URL war ungültig. Die Anforderung sollte dem Format „/tenantdomainname/Entity“ oder „/$metadata“ folgen. Der Domänenname für den Mandanten kann ein überprüfter oder ein nicht überprüfter Domänenname oder eine Kontext-ID sein.
400 Request_UnsupportedQuery Die GET-Anforderung wird nicht unterstützt. Beheben Sie die Anforderungsparameter, und versuchen Sie es erneut.
401 Authentication_ExpiredToken Das Zugriffstoken ist abgelaufen. Verlängern Sie das Token, bevor Sie die Anforderung erneut senden. Das Zugriffstoken ist abgelaufen. Verlängern Sie das Token, und senden Sie die Anforderung erneut.
401 Authentication_MissingOrMalformed Das Zugriffstoken fehlt oder ist fehlerhaft. Der access_token-Wert im Autorisierungsheader fehlt oder ist fehlerhaft. Dieser Wert ist erforderlich. Verwenden Sie den Wert im Authentifizierungstoken.
401 Authorization_IdentityDisabled Der aufrufende Anwendungsprinzipal ist deaktiviert. Der im Zugriffstoken angegebene Prinzipal befindet sich im Verzeichnis, ist jedoch deaktiviert. Aktivieren Sie das Konto im Verzeichnis erneut, und wiederholen Sie den Vorgang.
401 Authorization_IdentityNotFound Die Identität der aufrufenden Anwendung konnte nicht eingerichtet werden. Der im Zugriffstoken angegebene Prinzipal wurde nicht im Verzeichnis gefunden. Möglicherweise ist das Token veraltet, oder der Prinzipal wurde aus dem Verzeichnis gelöscht, oder die Verzeichnissynchronisierung ist verzögert.
403 Authentication_Unauthorized Nicht autorisierte Anforderung. Das Token enthält ungültige oder nicht unterstützte Ansprüche (Claims). Rufen Sie das Anforderungstoken erneut ab, und wiederholen Sie dann die Anforderung.
403 Authorization_RequestDenied Die angegebenen Anmeldeinformationen verfügen nicht über ausreichende Berechtigungen, um diese Anforderung zu senden. Die Anforderung wird aufgrund unzureichender Berechtigungen verweigert. Ein Prinzipal, der kein Administrator ist, hat beispielsweise keine Löschberechtigung für eine Ressource.
403 Directory_QuotaExceeded Der Grenzwert des Verzeichnisobjektkontingents für {tenantName} wurde überschritten. Bitten Sie den Administrator, die Kontingentgrenze heraufzusetzen oder Objekte zu löschen, um Kontingente freizugeben. Ein Verzeichniskontingent wurde überschritten. Möglicherweise verfügt der Mandant über zu viele Objekte, oder die Objekte weisen zu viele Werte auf. Eine Überschreitung kann auch auftreten, wenn zu viele Objekte für den Prinzipal erstellt werden. Erhöhen Sie die maximal zulässige Objektanzahl für den Mandanten oder Prinzipal, oder verringern Sie die Anzahl der in der Create-/Update-Anforderung enthaltenen Werte.
404 Directory_ObjectNotFound Die Unternehmensinformationen können nicht aus dem Verzeichnis gelesen werden.
404 Request_ResourceNotFound Die Ressource {resource} oder eines der abgefragten reference-property-Objekte ist nicht vorhanden. Die vom URI angegebene Ressource ist nicht vorhanden. Ändern Sie den Wert, und wiederholen Sie die Anforderung.
409 Request_MultipleObjectsWithSameKeyValue Als Ergebnis wurde eine einzige Ressource erwartet, aber es wurden mehrere Ressourcen gefunden. Aktualisieren Sie die Objekte, um den Konflikt aufzulösen. Dieser Fehler kann auftreten, wenn mindestens zwei Objekte denselben Schlüsselwert aufweisen, d.h. zwei Benutzer verwenden denselben UserPrincipalName.
429 Zu viele Anforderungen. Dieser Fehler tritt auf, wenn Anforderungen gedrosselt werden. Im Retry-After-Wert des Antwortheaders wird eine empfohlene Wartezeit zurückgegeben. Wiederholen Sie die Anforderung nach der empfohlenen Anzahl von Sekunden.
500 Service_InternalServerError Ein interner Serverfehler ist aufgetreten. Interner Serverfehler beim Verarbeiten der Anforderung.
502 [Alle] “... Dienst nicht verfügbar..." Ein Server, der als Gateway oder Proxy fungiert, hat bei der Verarbeitung der Anforderung einen Fehler von einem anderen Server festgestellt. Warten Sie einige Minuten, und wiederholen Sie dann die Anforderung.
503 Directory_ConcurrencyViolation Fehler aufgrund gleichzeitiger Anforderungen an den Mandanten. Warten Sie kurz, und versuchen Sie es noch mal.
503 Fehler bei der DNS-Überprüfung (Hinweis: Kann durch verschiedene Ursachen ausgelöst werden, z. B. weil der DNS momentan nicht betriebsbereit ist).
Authentication_Unknown Interner Serverfehler. Dieser Fehler wird verwendet, wenn andere Fehlercodes nicht zutreffend sind.
Authentication_UnsupportedTokenType Der dargestellte Tokentyp wird nicht verarbeitet. Nur Trägertoken werden unterstützt. Der Tokentyp wird nicht unterstützt. Ändern Sie den Tokentyp, bevor Sie die Anforderung wiederholen.
Directory_BindingRedirection Mandanteninformationen sind lokal nicht verfügbar. Verwenden Sie die folgenden URLs, um die Informationen abzurufen. Wenn die Mandantenpartition nicht im Datencenter verfügbar ist, müssen Clients eine Verbindung mit dem in der Antwort zurückgegebenen URI herstellen.
Directory_BindingRedirectionInternalServerError Mandanteninformationen sind lokal nicht verfügbar. Beim Versuch, die Liste der nächstliegenden Datencenter-Endpunkte aufzufüllen, hat der Server einen internen Fehler festgestellt. Wenn eine Bindungsumleitung auftritt, wird die Liste der nächstgelegenen Datencenter-Endpunkte für den Dienst aufgefüllt. Dieser Fehler weist auf eine Ausnahme beim Auffüllen der Liste hin. Wiederholen Sie die Abfrage.
Directory_CompanyNotFound Die Unternehmensinformationen können nicht aus dem Verzeichnis gelesen werden. Fehler beim Laden von Unternehmensinformationen aus dem Verzeichnisdienst.
Directory_ReplicaUnavailable Das bevorzugte Replikat ist nicht verfügbar. Wiederholen Sie den Vorgang ohne Header für den Replikatsitzungsschlüssel. Lassen Sie den x-ms-replica-session-key-Header weg, und wiederholen Sie den Vorgang.
Headers_DataContractVersionMissing Der Header der Datenvertragsversion fehlt. Schließen Sie x-ms-dirapi-data-contract-version in die Anforderung ein. Die Clientvertragsversion fehlt in der Anforderung.
Headers_HeaderNotSupported Der Header '{0}' wird derzeit nicht unterstützt. Die Anforderung enthält einen nicht unterstützten HTTP-Header. Ändern Sie den Header, und wiederholen Sie die Anforderung.
Request_InvalidReplicaSessionKey Der bereitgestellte Replikatsitzungsschlüssel ist ungültig. Korrigieren Sie den Replikatsitzungsschlüssel, und wiederholen Sie die Anforderung.
Request_ThrottledPermanently Die Anforderung wird dauerhaft gedrosselt. Wenden Sie sich zur Problembehebung an den Support. Der Mandant hat wiederholt den Grenzwert für die Tokenanforderungsrate überschritten. Anforderungen vom Mandanten werden zurückgewiesen, bis der Dienst erneut ausgehandelt wurde. Wenden Sie sich an den Microsoft Support, um Hilfe zu erhalten.

Zusätzliche Ressourcen