Fehlerbehandlung für Excel-APIs

Dieser Artikel enthält allgemeine Anweisungen und Vorschläge zur Behandlung von Fehlern, die von den Excel-APIs in Microsoft Graph zurückgegeben werden, wenn eine über die API gesendete Anforderung fehlschlägt.

Arten von Fehlerantworten

Excel-APIs in Microsoft Graph geben zwei Arten von Fehlern zurück. Eine ist die reguläre Fehlerantwort, die wie folgt aussieht.

HTTP/1.1 <HTTP status code>
Content-type: application/json
Retry-After: <Cooldown duration in seconds> (optional)

{
  "error": <Error object>
}

Die zweite stammt aus dem Muster mit zeitintensiven Vorgängen, das einen 200 OK HTTP-status-Code und failed -Vorgang zurückgeben kann, status im Antworttext, wie im folgenden Beispiel gezeigt.

HTTP/1.1 200 OK
Content-type: application/json

{
  "status": "failed",
  "error": <Error object>
}

Für beide Fehlerantworten weist das Fehlerobjekt die folgende Struktur auf.

Hinweis

Fehlerantworten entsprechen der Definition der OData v4-Spezifikation für Fehlerantworten.

{
  "code": "string",
  "message": "string",
  "innerError": { "@odata.type": "odata.error" }
}

Das innerError-Objekt kann rekursiv weitere innerError-Objekte mit zusätzlichen, spezifischeren Fehlercodes enthalten. Das Error-Objekt kann z. B. ausführlichere Fehlerinformationen im Fehlercode und der Meldung der zweiten Ebene enthalten, wie gezeigt.

{
  "code": "Top-level error code",
  "message": "Top-level error message",
  "innerError": {
    "code": "Second-level error code",
    "message": "Second-level error message",
    "innerError": { "@odata.type": "odata.error" }
  }
}

Schritte zum Behandeln von Fehlerantworten

Microsoft Graph-Clients müssen die folgenden Schritte ausführen, um Fehler zu behandeln, die mit Excel-APIs auftreten.

1. Ermitteln Sie, ob es sich um einen Zeitdauer-Vorgangsfehler handelt.

Vor der Behandlung eines Fehlers besteht der erste Schritt darin, zu bestimmen, ob die Fehlerantwort von einem Zeitintensiven Vorgangsmuster oder einem regulären Muster stammt. Ein Zeitintensiver Vorgangsfehler gibt einen 200 OK HTTP-status Code und failed einen Vorgang zurück, der im Antworttext status. Eine reguläre Fehlerantwort gibt einen entsprechenden HTTP-Fehler status Code zurück.

2. Analysieren des Fehlercodes der zweiten Ebene

Sowohl für das muster mit langer Ausführungsdauer als auch für das reguläre Muster sollte der Client zunächst die erforderlichen Fehlercodes der zweiten Ebene analysieren und sie gemäß den Anweisungen behandeln. Optional kann der Client auch andere Fehlercodes der zweiten Ebene verarbeiten oder auf Fehlercodes der obersten Ebene oder status Codes zurückgreifen.

Bei den Fehlercodes wird die Groß-/Kleinschreibung nicht beachtet.

Erforderliche Fehlercodes der zweiten Ebene

Die folgende Tabelle enthält Anweisungen für erforderliche Fehlercodes der zweiten Ebene, die von Microsoft Graph-Clients behandelt werden sollen. Der Dienst kann jederzeit neue Fehlercodes hinzufügen.

Code	Anweisungen
accessConflict	Die fehlgeschlagene Anforderung hat einen Konflikt mit anderen Clients, die auf die Arbeitsmappe zugreifen (z. B. hat ein anderer Client die Arbeitsmappe zur Bearbeitung gesperrt). Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet, bis der Konflikt behoben ist. Ein Endbenutzer kann die gleichen Vorgänge mit Excel Online manuell ausführen, um weitere Details zum Konflikt zu erhalten.
badRequestUncategorized	In der fehlerhaften Anforderung wird ein nicht angegebener Fehler gefunden. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
conflictUncategorized	Die fehlgeschlagene Anforderung verursacht einen Konflikt mit einem bestimmten Serverzustand. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet, bis der Konflikt behoben ist. Ein Endbenutzer kann die gleichen Vorgänge mit Excel Online manuell ausführen, um weitere Details zum Konflikt zu erhalten.
forbiddenUncategorized	Die fehlgeschlagene Anforderung ist nicht zulässig. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet. Ein Endbenutzer kann die gleichen Vorgänge mit Excel Online manuell ausführen, um weitere Details zu den Einschränkungen zu erhalten.
gatewayTimeoutUncategorized	Der Dienst konnte die Anforderung nicht innerhalb des Zeitlimits abschließen.
internalServerErrorUncategorized	Ein nicht angegebener Fehler ist aufgetreten. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet. Wenn in der fehlgeschlagenen Anforderung eine Sitzung angegeben wird, wird auch kein weiterer Zugriff auf die Sitzung erwartet.
invalidSessionAccessConflict	Die in der Anforderung angegebene Sitzung ist aufgrund von Konflikten mit anderen Clients ungültig, die auf die Arbeitsmappe zugreifen (z. B. hat ein anderer Client die Arbeitsmappe zur Bearbeitung gesperrt). Ein weiterer Zugriff auf die in der fehlgeschlagenen Anforderung angegebene Sitzung wird nicht erwartet. Das erneute Erstellen von Sitzungen mit derselben createSession-Anforderung wird erst erwartet, wenn der Konflikt gelöst ist. Das erneute Erstellen von Sitzungen mit einer anderen createSession-Anforderung kann oder nicht erfolgreich sein. Ein Endbenutzer kann die gleichen Vorgänge mit Excel Online manuell ausführen, um weitere Details zum Konflikt zu erhalten.
invalidSessionAuthentication	Die in der Anforderung angegebene Sitzung ist aufgrund eines Authentifizierungsfehlers ungültig. Ein weiterer Zugriff auf die in der fehlgeschlagenen Anforderung angegebene Sitzung wird nicht erwartet. Das erneute Erstellen von Sitzungen mit derselben createSession-Anforderung wird erst erwartet, wenn entsprechende Authentifizierungsinformationen bereitgestellt wurden.
invalidSessionNotFound	Die in der Anforderung angegebene Sitzung ist ungültig, da die Arbeitsmappe nicht gefunden werden kann. Ein weiterer Zugriff auf die in der fehlgeschlagenen Anforderung angegebene Sitzung wird nicht erwartet. Das Erneute Erstellen von Sitzungen mit derselben createSession-Anforderung ist nicht zu erwarten.
invalidSessionReCreatable	Die in der Anforderung angegebene Sitzung ist nicht vorhanden oder aufgrund eines vorübergehenden Fehlers ungültig. Der Microsoft Graph-Client kann versuchen, eine Sitzung neu zu erstellen und die Arbeit fortzusetzen. Ein weiterer Zugriff auf die in der fehlgeschlagenen Anforderung angegebene Sitzung wird nicht erwartet.
invalidSessionRestricted	Die in der Anforderung angegebene Sitzung ist aufgrund von Dienstkonfigurationen oder Einschränkungen ungültig. Ein weiterer Zugriff auf die in der fehlgeschlagenen Anforderung angegebene Sitzung wird nicht erwartet. Das erneute Erstellen von Sitzungen mit derselben createSession-Anforderung wird erst erwartet, wenn sich die Einschränkungen oder Konfigurationen ändern, die die Anforderung blockieren. Das erneute Erstellen von Sitzungen mit einer anderen createSession-Anforderung kann oder nicht erfolgreich sein. Ein Endbenutzer kann die gleichen Vorgänge manuell mit Excel Online ausführen, um weitere Details zu den Einschränkungen zu erhalten.
invalidSessionUnexpected	Die in der Anforderung angegebene Sitzung ist aufgrund eines unerwarteten Problems ungültig. Ein weiterer Zugriff auf die in der fehlgeschlagenen Anforderung angegebene Sitzung wird nicht erwartet. Das Erneute Erstellen von Sitzungen mit derselben createSession-Anforderung ist nicht zu erwarten. Das erneute Erstellen von Sitzungen mit einer anderen createSession-Anforderung kann oder nicht erfolgreich sein.
invalidSessionUnsupportedWorkbook	Die in der Anforderung angegebene Sitzung ist ungültig, da die Arbeitsmappe nicht unterstützte Features enthält oder die Größenbeschränkung überschreitet. In der Regel werden die nicht unterstützten Faktoren von einem anderen Client eingeführt, der auf die Arbeitsmappe zugreift. Ein weiterer Zugriff auf die in der fehlgeschlagenen Anforderung angegebene Sitzung wird nicht erwartet. Das erneute Erstellen von Sitzungen mit derselben createSession-Anforderung wird erst erwartet, wenn die nicht unterstützten Faktoren entfernt wurden. Das erneute Erstellen von Sitzungen mit einer anderen createSession-Anforderung kann oder nicht erfolgreich sein. Ein Endbenutzer kann die gleichen Vorgänge manuell mit Excel Online ausführen, um weitere Details zu den nicht unterstützten Faktoren zu erhalten, oder mit Excel Desktop, wo die Arbeitsmappe möglicherweise unterstützt wird.
methodNotAllowedUncategorized	Die in der Anforderung angegebene HTTP-Methode ist für die Ressource nicht zulässig. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
notFoundUncategorized	Die angeforderte Ressource wurde nicht gefunden. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
notImplementedUncategorized	Das angeforderte Feature ist derzeit nicht implementiert. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
payloadTooLargeUncategorized	Die Anforderungsnutzlast überschreitet die Größenbeschränkung. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
serviceUnavailableUncategorized	Der Dienst ist vorübergehend nicht verfügbar oder überlastet. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet, bis die angegebene Abkühldauer vorüber ist.
tooManyRequestsUncategorized	Die fehlgeschlagene Anforderung überschreitet bestimmte Häufigkeitsbeschränkungen. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet, bis die angegebene Abkühldauer vorüber ist. Bewährte Methoden zum Reduzieren der Drosselung finden Sie unter Reduzieren von Drosselungsfehlern.
transientFailure	Fehler bei der Anforderung aufgrund eines vorübergehenden Fehlers. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet, bis die angegebene Abkühldauer vorüber ist.
unauthorizedUncategorized	Die erforderlichen Authentifizierungsinformationen für die Ressource fehlen oder sind ungültig. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
unsupportedWorkbook	Fehler bei der Anforderung. Die Arbeitsmappe enthält nicht unterstützte Features oder überschreitet die Größenbeschränkung. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet, bis die nicht unterstützten Faktoren entfernt wurden.

Hinweis

Für das reguläre Muster wird die fehlgeschlagene Anforderung als die Anforderung definiert, die der Antwort entspricht. Für das Muster mit zeitintensiven Vorgängen ist die fehlgeschlagene Anforderung diejenige, die den fehlgeschlagenen Vorgang auslöst.

Optionale Fehlercodebeispiele der zweiten Ebene

Die folgende Tabelle enthält Beispiele für optionale Fehlercodes der zweiten Ebene, einschließlich der entsprechenden Behandlungsanweisungen für jeden Fehlercode. Der Dienst kann jederzeit neue Fehlercodes hinzufügen.

Code	Anweisungen
accessDenied	Sie können den angeforderten Vorgang nicht ausführen (z. B. Änderungen an gesperrten Zellen). Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
filteredRangeConflict	Der Vorgang ist fehlgeschlagen, weil er mit einem gefilterten Bereich in Konflikt kommt. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
generalException	Beim Verarbeiten der Anforderung ist ein interner Fehler aufgetreten. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
insertDeleteConflict	Der Einfüge- oder Löschvorgang führte zu einem Konflikt. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet. Ein Endbenutzer kann die gleichen Vorgänge mit Excel Online manuell ausführen, um weitere Details zum Konflikt zu erhalten.
invalidArgument	Das Argument ist ungültig, fehlt oder weist ein falsches Format auf. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
invalidReference	Dieser Verweis ist für den aktuellen Vorgang nicht gültig. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
itemAlreadyExists	Die erstellte Ressource ist bereits vorhanden. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
itemNotFound	Die angeforderte Ressource ist nicht vorhanden. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
methodNotAllowed	Die in der Anforderung angegebene HTTP-Methode ist für die Ressource nicht zulässig. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
nonBlankCellOffSheet	Neue Zellen können nicht eingefügt werden, da dadurch nicht leere Zellen vom Ende des Arbeitsblatts verschoben würden. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet. Ein Endbenutzer kann Zeilen oder Spalten löschen, um Platz für das Einfügen von Inhalten zu schaffen, und es dann erneut versuchen.
rangeExceedsLimit	Die Zellanzahl im Bereich hat die maximal unterstützte Anzahl überschritten. Der Microsoft Graph-Client kann versuchen, eine Anforderung mit einer kleineren Bereichsgröße zu senden. Weitere Informationen finden Sie unter Ressourcenlimits und Leistungsoptimierung für Office-Add-Ins.
requestAborted	Die Anforderung wurde während der Laufzeit abgebrochen, was in der Regel durch lange Zeitberechnungen von Funktionen in der Arbeitsmappe verursacht wurde. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.
unsupportedOperation	Dieser Vorgang wird nicht unterstützt. Es wird nicht erwartet, dass der Microsoft Graph-Client die fehlgeschlagene Anforderung erneut sendet.

Hinweis

Für das reguläre Muster wird die fehlgeschlagene Anforderung als die Anforderung definiert, die der Antwort entspricht. Für das Muster mit zeitintensiven Vorgängen ist die fehlgeschlagene Anforderung diejenige, die den fehlgeschlagenen Vorgang auslöst.

3. Analysieren des Fehlercodes der obersten Ebene

Wenn Sie keinen bekannten Fehlercode der zweiten Ebene finden können, sollten Sie die Anweisungen für Fehler der obersten Ebene befolgen. Die Fehlercodes der obersten Ebene sind an den status-Code gebunden, und Sie können entsprechend den entsprechenden status-Codes handeln. Ausführliche Informationen zu Fehlercodes und -meldungen der obersten Ebene finden Sie unter Fehlercodes und -meldungen.

4. Analysieren des status Codes

Wenn Sie für das reguläre Muster keinen bekannten Fehlercode der zweiten Ebene oder keinen Fehlercode der obersten Ebene finden konnten, sollten Sie maßnahmen gemäß dem HTTP-status-Code ausführen.

5. Fehlerwiederherstellung cooldown

Für einige Der Antworten im regulären Muster kann eine Wiederherstellungsabkühldauer in Sekunden über einen Retry-After Header bereitgestellt werden. Wenn eine Wiederherstellungsabkühlzeit vorliegt, wird erwartet, dass der Microsoft Graph-Client keine Folgeanforderungen sendet, bevor die angegebene Dauer verstreicht. Bewährte Methoden im Zusammenhang mit Retry-After Headern und Drosselung finden Sie unter Reduzieren von Drosselungsfehlern.

Diagnoseinformationen

Alle Inhalte in der Antwort, die in den vorherigen Schritten nicht verwendet wurden, dienen nur Diagnose Zweck (einschließlich Zeichenfolgen in den Nachrichtenfeldern). Es wird nicht empfohlen, eine Abhängigkeit von diesen Inhalten zu übernehmen, da sie sich ohne Vorheriges ändern können.

Sonderfallbehandlung

Wenn bei sitzungsbehafteten Anforderungen ein - oder 503/serviceUnavailable -502/badGatewayFehler auftritt, wenn ein bekannter Fehlercode der zweiten Ebene gefunden wird, befolgen Sie die entsprechenden Anweisungen. Andernfalls sollten Sie die Sitzung direkt neu erstellen.

Verwandte Inhalte

• Verwenden der Excel-REST-API