Fehler und Fehlerbehandlung

Wenn eine Anfrage für Firestore im Datastore-Modus erfolgreich ist, gibt die API einen HTTP-Statuscode 200 OK zusammen mit den angeforderten Daten im Text der Antwort zurück.

Wenn eine Anfrage fehlschlägt, gibt die Datastore API einen HTTP-Statuscode 4xx oder 5xx zurück, der den Fehler allgemein identifiziert, sowie eine Antwort, die Informationen zu den Fehlerursachen enthält.

Im Weiteren werden auf dieser Seite die Struktur eines Fehlers beschrieben, spezifische Fehlercodes aufgezählt und eine Fehlerbehebung empfohlen.

Dies ist die Struktur einer Fehlerantwort auf eine JSON-Anfrage:

{
  "error": {
    "code": "integer",
    "message": "string",
    "status": "string"
  }
}

Das Antwortobjekt enthält ein einzelnes Feld error, dessen Wert die folgenden Elemente umfasst:

Element Beschreibung
code Ein HTTP-Statuscode, der den Anfragefehler allgemein identifiziert.
message Spezifische Informationen zum Anfragefehler.
status Die kanonischen Fehlercode (google.rpc.Code) für Google APIs. Die Codes, die von der Datastore API zurückgegeben werden können, werden unter Fehlercodes aufgeführt.

Hier ein Beispiel einer Fehlerantwort auf eine JSON-Anfrage:

{
  "error": {
    "code": 400,
    "message": "Key path is incomplete: [Person: null]",
    "status": "INVALID_ARGUMENT"
  }
}

Wenn eine Anfrage mit dem Inhaltstyp application/x-protobuf zu einem Fehler führt, wird als Nutzlast die serialisierte Meldung google.rpc.Status zurückgegeben.

Fehlercodes

Es wird empfohlen, Fehler durch Prüfung des Werts des kanonischen Fehlercodes (google.rpc.Code) zu klassifizieren. Bei JSON-Fehlern wird dieser Code im Feld status angezeigt. Bei Fehlern vom Typ application/x-protobuf wird er im Feld code angezeigt.

Kanonischer Fehlercode Beschreibung Empfohlene Maßnahme
ABORTED Gibt an, dass ein Konflikt mit einer anderen Anfrage bestand. Bei einem nicht transaktionalen Commit:
Wiederholen Sie die Anfrage oder strukturieren Sie Ihre Entitäten, um Konflikte zu reduzieren.

Bei Anfragen, die Teil eines transaktional Commits sind:
Wiederholen Sie die gesamte Transaktion oder strukturieren Sie Ihre Entitäten, um Konflikte zu reduzieren.
ALREADY_EXISTS Gibt an, dass die Anfrage versucht hat, eine Entität einzufügen, die bereits vorhanden ist. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
DEADLINE_EXCEEDED Ein Zeitlimit wurde auf dem Server überschritten. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
FAILED_PRECONDITION Gibt an, dass eine Vorbedingung für die Anfrage nicht erfüllt war. Das Nachrichtenfeld der Fehlerantwort enthält Informationen zu der nicht erfüllten Vorbedingung. Eine mögliche Ursache ist die Ausführung einer Abfrage, die einen noch nicht definierten Index erfordert. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
INTERNAL Der Server hat einen Fehler zurückgegeben. Wiederholen Sie diese Anfrage nicht mehr als einmal.
INVALID_ARGUMENT Gibt an, dass ein Anfrageparameter einen ungültigen Wert hat. Im Nachrichtenfeld der Fehlerantwort ist angegeben, welcher Wert ungültig war. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
NOT_FOUND Gibt an, dass die Anfrage versucht hat, eine nicht vorhandene Entität zu aktualisieren. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
PERMISSION_DENIED Gibt an, dass der Nutzer nicht autorisiert war, die Anfrage zu stellen. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
RESOURCE_EXHAUSTED Gibt an, dass das Projekt entweder das Kontingent oder die Kapazität der Region/Multiregion überschritten hat. Prüfen Sie, ob Sie Ihr Projektkontingent überschritten haben. Wenn Sie ein Projektkontingent überschritten haben, wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.

Versuchen Sie es andernfalls mit exponentiellem Backoff.
UNAUTHENTICATED Gibt an, dass die Anfrage keine gültigen Authentifizierungsdaten enthielt. Wiederholen Sie den Vorgang nur, wenn das Problem behoben ist.
UNAVAILABLE Der Server hat einen Fehler zurückgegeben. Wiederholen Sie den Vorgang mit exponentiellem Backoff.