Microsoft Graph-Fehlerantworten und -Ressourcentypen

Fehler in Microsoft Graph werden mithilfe von HTTP-status Standardcodes und einem JSON-Fehlerantwortobjekt zurückgegeben.

HTTP-Statuscodes

In der folgenden Tabelle werden die HTTP-Statuscodes aufgeführt und beschrieben, die zurückgegeben werden können.

Statuscode	Statusmeldung	Beschreibung
400	Ungültige Anforderung (Bad Request)	Die Anforderung kann nicht verarbeitet werden, da sie falsch formatiert oder falsch ist.
401	Nicht autorisiert (Unauthorized)	Erforderliche Authentifizierungsinformationen fehlen oder sind für die Ressource nicht gültig.
402	Zahlung erforderlich	Die Zahlungsanforderungen für die API wurden nicht erfüllt.
403	Forbidden	Der Zugriff auf die angeforderte Ressource wird verweigert. Der Benutzer verfügt möglicherweise nicht über ausreichende Berechtigungen oder nicht über eine erforderliche Lizenz. Wichtig: Wenn Richtlinien für bedingten Zugriff auf eine Ressource angewendet werden, wird möglicherweise eine HTTP 403; Forbidden error=insufficient_claims Meldung zurückgegeben. Weitere Informationen zu Microsoft Graph und bedingtem Zugriff finden Sie unter Entwicklerleitfaden für Microsoft Entra bedingten Zugriff.
404	Nicht gefunden (Not Found)	Die angeforderte Ressource ist nicht vorhanden.
405	Methode nicht zulässig (Method Not Allowed)	Die HTTP-Methode in der Anforderung ist für die Ressource nicht zulässig.
406	Nicht zulässig (Not Acceptable)	Dieser Dienst unterstützt nicht das im Accept-Header angeforderte Format.
409	Conflict	Der aktuellen Status steht im Konflikt mit dem, was die Anforderung erwartet. Beispielsweise ist der angegebene übergeordnete Ordner nicht vorhanden.
410	Nicht vorhanden (Gone)	Die angeforderte Ressource ist nicht mehr auf dem Server verfügbar.
411	Länge erforderlich (Length Required)	Ein Content-Length-Header ist für die Anforderung erforderlich.
412	Fehler bei Vorbedingung (Precondition Failed)	Eine in der Anforderung angegebene Vorbedingung (z. B. ein if-match-Header) stimmt nicht mit dem aktuellen Zustand der Ressource überein.
413	Anforderungseinheit zu groß (Request Entity Too Large)	Die Größe der Anforderung überschreitet den zulässigen Höchstwert.
415	Nicht unterstützter Medientyp (Unsupported Media Type)	Der Inhaltstyp der Anforderung ist ein Format, das vom Dienst nicht unterstützt wird.
416	Angeforderter Bereich kann nicht erfüllt werden (Requested Range Not Satisfiable)	Der angegebene Bytebereich ist ungültig oder nicht verfügbar.
422	Einheit kann nicht bearbeitet werden (Unprocessable Entity)	Die Anforderung kann nicht verarbeitet werden, da sie semantisch falsch ist.
423	Gesperrt	Die Ressource, auf die zugegriffen wird, ist gesperrt.
429	Zu viele Anforderungen (Too Many Requests)	Die Clientanwendung wurde gedrosselt und sollte nicht versuchen, die Anforderung zu wiederholen, bis eine bestimmte Zeit verstrichen ist.
500	Interner Serverfehler (Internal Server Error)	Beim Verarbeiten der Anforderung ist ein interner Serverfehler aufgetreten.
501	Nicht implementiert (Not Implemented)	Das angeforderte Feature ist nicht implementiert.
503	Dienst nicht verfügbar (Service Unavailable)	Der Dienst ist wegen Wartung vorübergehend nicht verfügbar ist oder ist überlastet. Sie können die Anfrage nach einer Verzögerung wiederholen, deren Länge in einem Retry-After-Header angegeben werden kann.
504	Gateway-Timeout	Der Server, der als Proxy fungiert, hat keine rechtzeitige Antwort vom Upstream Server erhalten, auf den er zugreifen musste, um die Anforderung abzuschließen.
507	Unzureichender Speicher (Insufficient Storage)	Das maximale Speicherkontingent wurde erreicht.
509	Bandwidth Limit Exceeded	Die App wurde gedrosselt, da sie die maximale Bandbreite überschritten hat. Die App kann die Anforderung nach einiger Zeit wiederholen.

Die Fehlerantwort ist ein einzelnes JSON-Objekt, das eine einzige Eigenschaft mit dem Namen error enthält. Dieses Objekt enthält alle Fehlerdetails. Sie können die hier zurückgegebenen Informationen anstelle von oder zusätzlich zu dem HTTP-Statuscode verwenden. Nachfolgend finden Sie ein Beispiel für einen vollständigen JSON-Fehlertext.

{
  "error": {
    "code": "badRequest",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "code": "invalidRange",
      "request-id": "request-id",
      "date": "date-time"
    }
  }
}

Fehlerressourcentyp

Die Fehlerressource wird immer dann zurückgegeben, wenn ein Fehler bei der Verarbeitung der Anforderung auftritt.

Fehlerantworten folgen der Definition in den Microsoft-REST-API-Richtlinien.

JSON-Darstellung

Die Fehlerressource besteht aus einer einzelnen Ressource:

{
  "error": {
    "code": "string",
    "message": "string",
    "innererror": { 
      "code": "string"
    },
    "details": []
  }
}

Eigenschaftenname	Wert	Beschreibung
code	string	Eine Fehlercode-Zeichenfolge für den aufgetretenen Fehler
meldung	string	Eine entwicklerbereite Meldung über den aufgetretenen Fehler. Dies sollte dem Benutzer nicht direkt angezeigt werden.
innererror	Fehlerobjekt	Optional. Ein zusätzliches Fehlerobjekt, das möglicherweise spezifischer ist als der Fehler der obersten Ebene.
details	error object	Optional. Eine Liste zusätzlicher Fehlerobjekte, die eine Aufschlüsselung mehrerer Fehler bereitstellen können, die bei der Verarbeitung der Anforderung aufgetreten sind.

Eigenschaften

Die Codeeigenschaft enthält einen maschinenlesbaren Wert, von dem Sie eine Abhängigkeit in Ihrem Code annehmen können.

Das innererror-Objekt enthält möglicherweise rekursiv mehr innererror-Objekte mit zusätzlichen, spezifischeren Fehlercodeeigenschaften . Bei der Behandlung eines Fehlers sollten Apps alle verfügbaren geschachtelten Fehlercodes durchlaufen und den detailliertesten Fehlercode verwenden, den sie verstehen.

Die Meldungseigenschaft ist ein lesbarer Wert, der die Fehlerbedingung beschreibt. Nehmen Sie keine Abhängigkeit vom Inhalt dieses Werts in Ihrem Code auf.

Die Meldungseigenschaft im Stamm enthält eine Fehlermeldung, die der Entwickler lesen soll. Fehlermeldungen sind nicht lokalisiert und sollten dem Benutzer nicht direkt angezeigt werden. Bei der Behandlung von Fehlern sollte Ihr Code keine Abhängigkeit von den Nachrichteneigenschaftswerten annehmen, da sie sich jederzeit ändern können und häufig dynamische Informationen enthalten, die für die fehlgeschlagene Anforderung spezifisch sind. Sie sollten nur coden für Fehlercodes, die in Codeeigenschaften zurückgegeben werden.

Die details-Eigenschaft ist ein optionales Array von Fehlerobjekten, die das gleiche JSON-Format wie das Fehlerobjekt der obersten Ebene aufweisen. Bei einer Anforderung, die aus mehreren Vorgängen besteht, z. B. einem Massen- oder Batchvorgang, kann es erforderlich sein, für jeden Vorgang einen unabhängigen Fehler zurückzugeben. In diesem Fall wird die Detailliste mit diesen einzelnen Fehlern aufgefüllt.