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.