Empfehlungen API-Antwortcodes

Gilt für: Partner Center | Partner Center-Empfehlungen

Geeignete Rollen: Empfehlungsadministrator | Empfehlungsbenutzer

Die REST-APIs für Partner Center-Verweise geben ein JSON-Objekt zurück, das einen Statuscode enthält. Dieser Code, der angibt, ob die Anforderung erfolgreich war oder warum sie fehlgeschlagen ist.

Erfolgsantworten

Ein 2xx-Statuscode gibt an, dass die Anforderung des Clients erfolgreich empfangen, verstanden und akzeptiert wurde. Die folgenden 2xx-Statuscodes geben eine Erfolgsantwort an:

• 200: Erfolg bestätigt
• 201: Ressource erstellt
• 202: Akzeptiert
• 204: Kein Inhalt, der zurückgegeben werden soll

Fehlercodes

Jede Antwort mit einem 4xx - oder 5xx-Statuscode enthält eine Fehlermeldung mit Details zu den Fehlerbedingungen für diesen Code.

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

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.
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 bereitgestellte Voraussetzung (z. B. ein If-Match-Header) stimmt nicht mit dem aktuellen Zustand der Ressource überein.
413	Anforderungsentität zu groß	Die angeforderte Größe übersteigt den zulässigen Maximalwert.
415	Nicht unterstützter Medientyp	Der Inhaltstyp der Anforderung ist 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 Clientanwendung wird gedrosselt und sollte nicht versuchen, die Anforderung einige Zeit lang zu wiederholen.
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	Gateway-Timeout	Der Server, während er als Proxy fungiert, hat keine rechtzeitige Antwort vom Upstreamserver erhalten, auf den er zugreifen musste, 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	Die Clientanwendung wurde gedrosselt, um die maximale Bandbreitengrenze zu überschreiten. Ihre App kann die Anforderung nach einiger Zeit erneut versuchen.

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.

Die folgende Tabelle und Codebeispiele beschreiben das Schema einer Fehlerantwort.

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 stellt weitere Debuginformationen bereit. Ungleich NULL nicht. Die maximale Länge beträgt 1.024 Zeichen.
innerError	Objekt	Optional. Ein weiteres Fehlerobjekt mit spezifischeren Informationen zum Fehler.
innerError.code	numerische Zeichenfolge	Wird immer zurückgegeben, wenn innerError ungleich Null ist. Enthält spezifischere Fehlercodeinformationen unter dem obersten Fehlercodewert.
innerError.message	Zeichenfolge	Wird immer zurückgegeben, wenn innerError ungleich Null ist. Stellt eine spezifischere Fehlermeldung unter der obersten Fehlermeldungszeichenfolge bereit.
innerError.details	array object	Optional. Enthält weitere Details zum Fehler. In erster Linie nützlich bei Eingabeüberprüfungsfehlern.
target	Zeichenfolge	Optional. Das Ziel, auf das der Fehler zurückzuführen ist.

Beispielfehlerantwort

{
  "error": {
    "code": "unauthenticated",
    "message": "The caller is not authenticated.",
    "innerError": {
      "code": "99902",
      "message": "Request not authenticated",
      "details": null
    }
  }
}

Ein weiteres Beispiel mit dem aufgefüllten Objekt innerError.details :

{
  "error": {
    "code": "invalidRequest",
    "message": "The request is malformed or incorrect.",
    "innerError": {
      "code": "99901",
      "message": "InvalidInput",
      "details": [
        {
          "InvalidReferralForCoSellConversion": [
            "If PartnerLed referral has no solution it cannot be converted to co-sell referral"
          ]
        }
      ]
    }
  }
}

Eigenschaft „code“

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

Code	Http-Statuscode	Beschreibung
invalidRequest	400	Die Anforderung ist fehlerhaft oder falsch.
unauthenticated	401	Der Aufrufer ist nicht authentifiziert.
accessDenied	403	Der Aufrufer ist nicht zum Ausführen der Aktion berechtigt.
itemNotFound	404	Die Ressource konnte nicht gefunden werden.
resourceModified	409	Die Ressource, die seit dem letzten Lesen der Ressource geändert wird, ist in der Regel ein eTag-Konflikt.
preconditionFailed	412	Eine in der Anforderung bereitgestellte Voraussetzung (z. B. ein If-Match-Header) stimmt nicht mit dem aktuellen Zustand der Ressource überein.
generalException	500	Es ist ein unbekannter Fehler aufgetreten.
serviceNotAvailable	503	Der Dienst ist nicht verfügbar. Wiederhole die Anforderung nach einer Verzögerung. Möglicherweise ist ein Retry-After-Header vorhanden.

Nachrichteneigenschaft

Die Eigenschaft message am Stamm enthält eine Fehlermeldung für den Entwickler. Fehlermeldungen werden nicht lokalisiert und sollten nicht direkt für den Benutzer angezeigt werden. Ihr Code sollte nicht nur auf message Werte überprüfen, weil sie sich jederzeit ändern können, und sie enthalten häufig dynamische Informationen, die für die fehlgeschlagene Anforderung spezifisch sind. Sie sollten code against error codes returned in code properties and then for more details combine it with message text.

Objekt „InnerError“

Das innererror Objekt kann rekursiv weitere innererror Objekte mit spezifischeren Fehlercodes enthalten. Clientanwendung sollte bei der Behandlung eines Fehlers alle verfügbaren Fehlercodes durchlaufen und den detailliertesten code verwenden, den sie verstehen.

Es gibt einige weitere Fehler, auf die Ihre App innerhalb der geschachtelten innererror Objekte stoßen kann. Apps sind nicht erforderlich, um diese Fehler zu behandeln, können dies jedoch tun, wenn sie dies auswählen. Der Dienst kann neue Fehlercodes hinzufügen oder die Rückgabe alter Fehlercodes jederzeit beenden. Daher ist es wichtig, dass alle Apps in der Lage sind, die [grundlegenden Fehlercodes] zu behandeln.

Fehlercodes

Es folgen Fehlercodes, die von den APIs zurückgegeben werden:

HTTP-Status	HTTP-Fehlercode	Fehlercode	BESCHREIBUNG
BadRequest	400	99901	Ungültige Eingabe
Nicht autorisiert	401	99902	Nicht autorisierter Zugriff
BadRequest	400	99903	Fehlende Eingabe
NotFound	404	99,904	Ressource nicht gefunden
InternalServerError	500	99905	Fehler nicht angegeben
TooManyRequests	429	99906	Zu viele Anforderungen
InternalServerError	500	99907	Vorübergehender interner Fehler
BadRequest	400	99908	Die Eigenschaft ist nicht aktualisierbar.
BadRequest	400	99909	Die Eigenschaft ist nicht nullwertebar.
VorbedingungFailed	412	99910	Der Etag-Wert stimmt nicht überein.
BadRequest	400	99911	Ungültiger Empfehlungsstatus zum Einladen
BadRequest	400	99912	Die Lösung mit dem Typ "Name" ist erforderlich.
Verboten	403	99913	Organisation nicht zugelassen zum Erstellen einer Ressource
Verboten	403	99914	Organisation nicht zugelassen, an Co-Sell-Engagements teilzunehmen
InternalServerError	500	99915	Interner Anforderungsausführungsfehler
Konflikt	409	99917	Ressource wurde bereits über eine andere Anforderung geändert
PreConditionFailed	412	99918	Eine in der Anforderung bereitgestellte Voraussetzung (z. B. ein If-Match-Header) stimmt nicht mit dem aktuellen Zustand der Ressource überein.
BadRequest	400	99919	Ungültige Empfehlungsqualifizierung zum Aktualisieren
InternalServerError	500	99999	Allgemeine Ausnahme während der Verarbeitungsanforderung