Weegloo Docs - Fehler

Schlägt ein Request fehl, gibt WEEGLOO einen Fehler-Body in einem einheitlichen Format zusammen mit einem HTTP-Statuscode zurück. Die Form des Response-Body ist unabhängig davon gleich, in welcher API (CMA, CDA, ACMA, ACDA, Upload, Auth) der Fehler aufgetreten ist. Wer also nur ein einziges Format zu verarbeiten weiß, kann alle Fehler auf dieselbe Weise verzweigen. Diese Seite fasst dieses gemeinsame Format und die häufig auftretenden Fehlercodes an einem Ort zusammen.

Format der Fehlerantwort

Der Fehler-Body hat die folgende Form. Unten steht die Response, die beim Abfragen eines nicht vorhandenen WebHosting zurückkam.

{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } }
  },
  "reason": "WebHosting(...) has been deleted or does not exist.",
  "suggestion": "Please verify WebHosting and try again."
}

Die Bedeutung der einzelnen Schlüssel ist wie folgt.

Schlüssel	Typ	Beschreibung
`requestId`	string	Nachverfolgungs-Kennung dieses Requests. Geben Sie diesen Wert bei Anfragen an den Support mit, damit der betreffende Request schnell gefunden werden kann.
`sys.type`	string	Fehlerklassifizierung. Bezeichnet die grobe Kategorie wie `Unauthorized`, `Forbidden`, `NotFound`, `Unprocessable`, `Conflict`, `TooManyRequest`.
`sys.code`	string	Detaillierter Fehlercode (z. B. `WGL409005`). Diesen Wert verwenden Sie, wenn Sie auf Code-Ebene verzweigen.
`sys.timestamp`	integer	Zeitpunkt des Fehlers (Epoch-Millisekunden).
`reason`	string	Menschenlesbarer Fehlergrund.
`suggestion`	string	Hinweis zur Behebung.
`details`	object (optional)	Zusatzinformationen. Enthält etwa einen `Refer`, der auf die zugehörige Ressource verweist, oder eine Liste der Validierungsfehler-Einträge (`errors`). Kann je nach Fehlerart fehlen.

Die Verzweigung erfolgt nach Bedarf auf der Ebene von sys.type (grobe Kategorie) oder sys.code (detaillierter Code). Auch bei gleichem sys.type ist die Ursache eine andere, wenn der sys.code abweicht. Für eine genaue Verarbeitung orientieren Sie sich daher an sys.code.

Schlägt die Validierung fehl, werden die fehlerhaften Einträge in details.errors abgelegt. Unten steht die Response einer fehlgeschlagenen Validierung, bei der dem Body eine Eigenschaft hinzugefügt wurde, die nicht im Schema vorhanden ist.

{
  "requestId": "yJ8KpQ2mWtnLrZ4Xv7BcEadfh3sNuMvKbGT5Pq9wRsx",
  "sys": {
    "id": "Lm2Nq9Tr8KdW4xZc",
    "type": "BadRequest",
    "code": "WGL400006",
    "timestamp": 1781776000000
  },
  "details": {
    "errors": [
      { "path": "", "message": "property 'X' is not defined in the schema", "property": "X" }
    ]
  },
  "reason": "Some values do not satisfy validation rules.",
  "suggestion": "Please check the request body and try again."
}

Jeder Eintrag in details.errors enthält die fehlerhafte Position (path), eine Beschreibung (message) und den Namen der betroffenen Eigenschaft (property). Gibt es mehrere Einträge, kommt pro fehlerhaftem Wert je einer hinzu.

Häufig auftretende Codes

Die folgenden Fehlercodes treten häufig auf.

Code	Klassifizierung	Bedeutung	Häufige Situation
`WEB401001`	`Unauthorized`	Token ungültig	Das Bearer-Token im `Authorization`-Header ist abgelaufen oder fehlerhaft.
`WGL403001`	`Forbidden`	Keine Berechtigung	Die Rolle des Aufrufers erlaubt diese Aktion nicht.
`WGL404001`	`NotFound`	Ressource nicht vorhanden oder gelöscht	Abfrage mit einer falschen `sys.id` oder Aufruf einer noch nicht eingerichteten Funktion (z. B. keine eigene Domain verbunden).
`WGL400006`	BadRequest	Body-Wert verstößt gegen Validierungsregeln	Der Body wurde mit einem falschen Feldschlüssel oder Typ gesendet. Die fehlerhaften Einträge werden in `details.errors` abgelegt.
`WGL409005`	`Conflict`	Ressource wurde zwischenzeitlich geändert	Der Header `X-Weegloo-Version` fehlt oder weicht von der aktuellen Version ab (siehe Konventionen).
`WGL422007`	`Unprocessable`	Im veröffentlichten Zustand nicht archivierbar	Um Content oder Media zu archivieren, muss zuvor die Veröffentlichung zurückgezogen werden.
`WGL422009`	`Unprocessable`	Im veröffentlichten Zustand nicht löschbar	Um veröffentlichten Content oder veröffentlichtes Media zu löschen, muss zuvor die Veröffentlichung zurückgezogen werden.
`WGL429001`	`TooManyRequest`	Plangrenze überschritten	Die Anzahl erstellter Ressourcen wie Organization oder Space überschreitet die Grenze des aktuellen Plans. Mit einem höheren Plan steigt die Grenze.

Die obigen Codes sind nur eine häufig auftretende Auswahl. Darüber hinaus kann es je nach Aktion und Ressource weitere Codes geben. Welchen Code Sie auch erhalten: Erfassen Sie über sys.type die grobe Kategorie und prüfen Sie über reason und suggestion die konkrete Ursache und die Richtung der Behebung.

Konventionen: Die Nebenläufigkeitsregel mit X-Weegloo-Version, um WGL409005 zu vermeiden.
Systemeigenschaften (sys): Der Veröffentlichungszustand (status) und der Lebenszyklus, auf den WGL422007 und WGL422009 verweisen.

Format der Fehlerantwort

Häufig auftretende Codes

Verwandte Dokumente