Die API folgt einem strukturierten Ansatz zur Fehlerbehandlung und bietet aussagekräftiges Feedback, wenn Anfragen aufgrund von Validierungsproblemen, Verstößen gegen Geschäftsregeln oder anderen unerwarteten Bedingungen fehlschlagen. Obwohl es interne Standards für die Rückgabe von Fehlern gibt, kann die Implementierung je nach Abfrage/Mutation variieren.
Antwortverhalten und HTTP-Statuscodes
In den meisten Fällen gibt die API einen HTTP 200 OK-Status zurück, selbst wenn ein Fehler auftritt. Dies liegt daran, dass GraphQL-Fehler im Antwortkörper und nicht über HTTP-Statuscodes behandelt werden. Eine der Ausnahmen ist der Statuscode 429 - Zu viele Anfragen, der zurückgegeben wird, wenn die Ratenbegrenzungen überschritten werden. Andere Statuscodes, wie solche, die auf Authentifizierungs- oder Verfügbarkeitsprobleme hinweisen, können verwendet werden.
Validierungsfehler
Wenn die Eingabe nicht den erwarteten Anforderungen entspricht, beispielsweise wenn Geschäftsregeln nicht befolgt werden, enthält die Antwort eine Liste von Validierungsfehlern. Bei Mutationen, die eine Eingabevalidierung durchführen, folgt die Antwort typischerweise dieser Struktur:
type UpdateActivityResult {
validationErrors: [ValidationErrors]
item: Activity
}Wenn die Validierung fehlschlägt, wird die Eigenschaft item normalerweise auf ihren Standardwert gesetzt, und die Eigenschaft validationErrors liefert Details zum Problem. Das Nachrichtenfeld bietet umsetzbare Hinweise.
Beispiel: Validierungsfehlerantwort
{
"data": {
"updateActivity": {
"item": null,
"validationErrors": [
{
"message": "ActivityDate muss im Format 'yyyy-MM-dd HH:mm:ss' sein",
"propertyName": "ActivityDate"
}
]
}
}
}Allgemeine Fehler
Fehler, die nicht mit der Validierung zusammenhängen, wie interne Verarbeitungsfehler, Probleme mit externen Diensten oder unerwartete Bedingungen, werden in der Fehlerkollektion der GraphQL-Antwort zurückgegeben.
Diese Fehler enthalten typischerweise Folgendes:
- Nachricht: Eine Beschreibung des Fehlers.
- Erweiterungen: Zusätzliche Metadaten wie Fehlercodes oder kontextbezogene Informationen.
Beispiel: Allgemeine Fehlerantwort
{
"data": {
"addActivity": null
},
"errors": [
{
"message": "Methodenanfrage mit [220] fehlgeschlagen Zeitstempelformat
muss yyyy-mm-dd hh:mm:ss[.fffffffff] für addActivity sein",
"extensions": {
"code": "APP_SERVER_METHOD",
"data": {
"activityId": "00-ebaa2c159c436a4a8e4c6bd086e33b2b-4927fca7e17ec948-00"
}
}
}
]
}Überlegungen
- Obwohl die oben genannten Standards im Allgemeinen befolgt werden, stimmen einige Abfragen/Mutationen möglicherweise noch nicht vollständig mit ihnen überein. Drittanbieter-Clients sollten sowohl strukturierte Validierungsfehler als auch allgemeine GraphQL-Fehler angemessen behandeln.
- Drittanbieter-Clients sollten immer den Antwortkörper auf Fehlerdetails überprüfen, anstatt sich ausschließlich auf HTTP-Statuscodes zu verlassen.