Partner-API: REST-Fehlercodes

Gilt für:

  • Partner-API

Fehler in Partner-REST-APIs werden mithilfe standardmäßiger HTTP-Statuscodes sowie mithilfe eines JSON-Fehlerantwortobjekts zurückgegeben.

HTTP-Statuscodes

In der folgenden Tabelle werden die möglichen HTTP-Statuscodes aufgelistet und beschrieben:

Statuscode Statusmeldung BESCHREIBUNG
400 Ungültige Anforderung Die Anforderung kann nicht verarbeitet werden, da sie fehlerhaft oder falsch ist.
401 Nicht autorisiert Die erforderlichen Authentifizierungsinformationen sind entweder nicht vorhanden oder für die Ressource nicht gültig.
403 Verboten Der Zugriff auf die angeforderte Ressource wurde verweigert. Der Benutzer verfügt möglicherweise nicht über die erforderliche Berechtigung. Wichtig: Wenn auf eine Ressource Richtlinien für bedingten Zugriff angewendet wurden, wird unter Umständen HTTP 403; Forbidden error=insufficent_claims zurückgegeben. Ausführlichere Informationen zu Microsoft Graph und bedingtem Zugriff findest du in der Anleitung für Entwickler zum bedingten Zugriff mit Azure Active Directory.
404 Nicht gefunden Die angeforderte Ressource ist nicht vorhanden.
405 Methode nicht zulässig Die HTTP-Methode in der Anforderung ist für die Ressource nicht zulässig.
406 Nicht annehmbar Dieser Dienst unterstützt das im Accept-Header angeforderte Format nicht.
409 Konflikt: Der aktuelle Zustand entspricht nicht den Erwartungen der Anforderung. Beispiel: Der angegebene übergeordnete Ordner ist nicht vorhanden.
410 Fehlend Die angeforderte Ressource ist auf dem Server nicht mehr verfügbar.
411 Länge erforderlich Für die Anforderung ist ein Content-Length-Header erforderlich.
412 Vorbedingung nicht erfüllt Eine in der Anforderung angegebene Vorbedingung (beispielsweise ein If-Match-Header) entspricht nicht dem aktuellen Zustand der Ressource.
413 Anforderungsentität zu groß Die angeforderte Größe übersteigt den zulässigen Maximalwert.
415 Nicht unterstützter Medientyp Bei dem Inhaltstyp der Anforderung handelt es sich um ein Format, das vom Dienst nicht unterstützt wird.
416 Angeforderter Bereich kann nicht erfüllt werden Der angegebene Bytebereich ist ungültig oder nicht verfügbar.
422 Einheit kann nicht bearbeitet werden 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 Die Client Anwendung wurde gedrosselt, und die Anforderung sollte erst nach einer gewissen Zeit wiederholt werden.
500 Interner Serverfehler Bei der Verarbeitung der Anforderung ist ein interner Serverfehler aufgetreten.
501 Nicht implementiert Das angeforderte Feature ist nicht implementiert.
503 Dienst nicht verfügbar Der Dienst ist wartungs- oder überlastungsbedingt vorübergehend nicht verfügbar. Du kannst die Anforderung nach einer gewissen Verzögerung wiederholen. Die Verzögerung kann in einem Retry-After-Header angegeben werden.
504 Gatewaytimeout Der als Proxy fungierende Server hat nicht rechtzeitig eine Antwort von dem Upstreamserver erhalten, auf den er Zugriff benötigte, um die Anforderung abzuschließen. Dieser Fehler kann in Verbindung mit dem Fehler 503 auftreten.
507 Unzureichender Speicher Das maximale Speicherkontingent wurde erreicht.
509 Bandbreitenlimit überschritten Deine App wurde gedrosselt, da die Bandbreitenobergrenze überschritten wurde. Die Anforderung kann etwas später wiederholt werden.

Die Fehlerantwort ist ein einzelnes JSON-Objekt, das eine einzelne Eigenschaft namens error enthält. Dieses Objekt enthält sämtliche Fehlerdetails. Die hier zurückgegebenen Informationen können anstelle des HTTP-Statuscodes oder als Ergänzung verwendet werden. Im Anschluss findest du ein Beispiel für einen vollständigen JSON-Fehlertext.

Fehlerressourcentyp

Die Fehlerantwort ist ein einzelnes JSON-Objekt, das eine einzelne Eigenschaft namens error enthält. Dieses Objekt enthält sämtliche Fehlerdetails. Die hier zurückgegebenen Informationen können anstelle des HTTP-Statuscodes oder als Ergänzung verwendet werden. Im Anschluss findest du ein Beispiel für einen vollständigen JSON-Fehlertext.

In der folgenden Tabelle und im folgenden Codebeispiel wird das Schema einer Fehlerantwort beschrieben:

Name Typ BESCHREIBUNG
code Zeichenfolge Wird immer zurückgegeben. Gibt die Art des aufgetretenen Fehlers an. Ist nicht NULL.
message Zeichenfolge Wird immer zurückgegeben. Beschreibt den Fehler im Detail und enthält zusätzliche Debuginformationen. Ist nicht NULL und nicht leer. Die maximale Länge beträgt 1.024 Zeichen.
innerError Objekt (object) Optional. Zusätzliches Fehlerobjekt, das ggf. spezifischer ist als der Fehler auf oberster Ebene.
target Zeichenfolge Das Ziel, auf das der Fehler zurückzuführen ist.

Eigenschaft „code“

Die Eigenschaft code enthält einen der folgenden möglichen Werte. Deine Apps sollten jeden dieser Fehler behandeln können.

Code BESCHREIBUNG
accessDenied Der Aufrufer ist nicht zum Ausführen der Aktion berechtigt.
generalException Ein unbekannter Fehler ist aufgetreten.
invalidRequest Die Anforderung ist fehlerhaft oder falsch.
itemNotFound Die Ressource wurde nicht gefunden.
preconditionFailed Eine in der Anforderung angegebene Vorbedingung (beispielsweise ein If-Match-Header) entspricht nicht dem aktuellen Zustand der Ressource.
resourceModified Die zu aktualisierende Ressource hat sich seit dem letzten Lesevorgang des Aufrufers geändert (in der Regel ein ETag-Konflikt).
serviceNotAvailable Der Dienst ist nicht verfügbar. Wiederhole die Anforderung nach einer Verzögerung. Möglicherweise ist ein Retry-After-Header vorhanden.
unauthenticated Der Aufrufer ist nicht authentifiziert.

Nachrichteneigenschaft

Die Eigenschaft message am Stamm enthält eine Fehlermeldung für den Entwickler. Fehlermeldungen werden nicht lokalisiert und sollten Benutzern nicht direkt angezeigt werden. Bei der Behandlung von Fehlern sollte Ihr Code keine Überprüfung auf Werte ausführen, da sie jederzeit geändert werden können und häufig dynamische Informationen enthalten, die spezifisch für die message fehlgeschlagene Anforderung sind. Berücksichtige in deinem Code nur Fehlercodes, die in Eigenschaften vom Typ code zurückgegeben werden.

Objekt „InnerError“

Das Objekt innererror kann rekursiv mehrere Objekte vom Typ innererror mit zusätzlichen, spezifischeren Fehlercodes enthalten. Bei der Fehlerbehandlung sollten Apps sämtliche verfügbaren Fehlercodes durchlaufen und den detailliertesten Code verwenden, der für sie verständlich ist.

Es gibt noch einige weitere Fehler, auf die deine App in den geschachtelten Objekten vom Typ innererror treffen kann. Die Behandlung dieser Fehler ist für Apps optional. Da der Dienst jederzeit neue Fehlercodes hinzufügen oder die Rückgabe alter Fehler einstellen kann, ist es wichtig, dass alle Apps die [grundlegenden Fehlercodes] behandeln können.

{
  "error": {
    "code": "unAuthorized",
    "message": "Caller is not authorized to access the resource.",
    "target": "referral",
    "innerError": {
      "code": "innerErrorCode",
      "message": "Unauthorized referral access"
    }
  }
}