Table of contents

Fehlercodes und Fehlerbehandlung | Graph-API-Konzepte

Jimaco Brannian|Zuletzt aktualisiert: 22.02.2017
|
1 Mitwirkender

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

Die Funktionen der Azure AD Graph-API sind auch über Microsoft Graph verfügbar. Dies ist eine einheitliche API, die auch APIs von anderen Microsoft-Diensten wie Outlook, OneDrive, OneNote, Planner und Office Graph enthält. Auf alle wird über einen einzigen Endpunkt mit einem einzigen Zugriffstoken zugegriffen.

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-StatuscodeFehlercodeFehlermeldungDetails
400Directory_ExpiredPageTokenDer angegebene Seitentokenwert ist abgelaufen und kann nicht länger in Ihrer Anforderung verwendet werden.
400Directory_ResultSizeLimitExceededGrößenbeschränkung des Resultsets wurde überschrittenDie Anforderung kann nicht beantwortet werden, da ihr zu viele Ergebnisse zugeordnet ist. Dieser Fehler tritt nur sehr selten auf.
400DomainVerificationCodeNotFoundFehler bei der Domänenüberprüfung, da bei der Überprüfung kein TXT-Eintrag mit übereinstimmendem Überprüfungscode gefunden wurde.
400ObjectConflictDer Domänenname ist bereits in einer nicht überprüften Domäne in diesem Unternehmen vorhanden.
400ObjectConflictDer Domänenname ist bereits in einer überprüften Domäne in diesem Unternehmen vorhanden.
400ObjectInUseDie Domäne, die momentan von einem Benutzer, einer Gruppe oder einer Anwendung mit mehreren Mandanten referenziert wird, kann nicht gelöscht werden.
400ObjectPendingDeletionEine vorhandene Domäne, deren Löschvorgang aussteht, kann nicht überprüft werden.
400ObjectPendingTakeoverEine Domäne, für die gerade eine Mandantenübernahme ausgeführt wird, kann nicht gelöscht werden.
400Request_BadRequestUngü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.
400Request_DataContractVersionMissingDer Parameter für die Datenvertragsversion fehlt. Schließen Sie „api-version“ als Abfrageparameter in sämtliche Ihrer Anforderungen ein.
400Request_InvalidDataContractVersionDie angegebene „api-version“ ist ungültig. Der Wert muss mit einer unterstützten Version übereinstimmen.
400Request_InvalidRequestUrlDie 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.
400Request_UnsupportedQueryDie GET-Anforderung wird nicht unterstützt. Beheben Sie die Anforderungsparameter, und versuchen Sie es erneut.
401Authentication_ExpiredTokenDas 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.
401Authentication_MissingOrMalformedDas 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.
401Authorization_IdentityDisabledDer 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.
401Authorization_IdentityNotFoundDie 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.
403Authentication_UnauthorizedNicht 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.
403Authorization_RequestDeniedDie 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.
403Directory_QuotaExceededDer 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.
404Directory_ObjectNotFoundDie Unternehmensinformationen können nicht aus dem Verzeichnis gelesen werden.
404Request_ResourceNotFoundDie 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.
409Request_MultipleObjectsWithSameKeyValueAls 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.
429Zu 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.
500Service_InternalServerErrorEin 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.
503Directory_ConcurrencyViolationFehler aufgrund gleichzeitiger Anforderungen an den Mandanten. Warten Sie kurz, und versuchen Sie es noch mal.
503Fehler bei der DNS-Überprüfung (Hinweis: Kann durch verschiedene Ursachen ausgelöst werden, z. B. weil der DNS momentan nicht betriebsbereit ist).
Authentication_UnknownInterner Serverfehler.Dieser Fehler wird verwendet, wenn andere Fehlercodes nicht zutreffend sind.
Authentication_UnsupportedTokenTypeDer 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_BindingRedirectionMandanteninformationen 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_BindingRedirectionInternalServerErrorMandanteninformationen 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_CompanyNotFoundDie Unternehmensinformationen können nicht aus dem Verzeichnis gelesen werden.Fehler beim Laden von Unternehmensinformationen aus dem Verzeichnisdienst.
Directory_ReplicaUnavailableDas 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_DataContractVersionMissingDer Header der Datenvertragsversion fehlt. Schließen Sie x-ms-dirapi-data-contract-version in die Anforderung ein.Die Clientvertragsversion fehlt in der Anforderung.
Headers_HeaderNotSupportedDer 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_InvalidReplicaSessionKeyDer bereitgestellte Replikatsitzungsschlüssel ist ungültig.Korrigieren Sie den Replikatsitzungsschlüssel, und wiederholen Sie die Anforderung.
Request_ThrottledPermanentlyDie 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

© 2017 Microsoft