Das Fehlerformat

Worum es geht

Geht eine Anfrage schief, antwortet CDMS mit einem Fehlerstatus (400 und höher) und einer Fehlerantwort. Die Fehlerantwort ist ein kleines JSON-Objekt ohne data. Es sagt dir, was passiert ist, und zwar so, dass ein Programm es auswerten kann.

Eine Fehlerantwort, beschriftet

POST /api/rest/hr/employee/read/5a2b…
{ "response": ["name"] }

{
  "error":      "MissingPermissionException",   ← Art des Fehlers
  "messageKey": "missing-permission|hr-employee-read",
                 └ Schlüssel ┘ └── Detail ───┘  ← hierauf verzweigen
  "code":       "403",                          ← Status als Text
  "layer":      "validation"                    ← Schicht, nur zur Fehlersuche
}

Der messageKey im Einzelnen

Der messageKey hat die Form schlüssel|detail|detail. Vor dem ersten | steht der Schlüssel, also die Art des Problems. Danach folgen, je nach Fehler, Details wie ein Feldname, ein Rollenname, eine id oder ein Wert.

So kommst du im Client an den Schlüssel:

const [key, ...details] = body.messageKey.split('|');
// key     = "missing-permission"
// details = ["hr-employee-read"]

switch (key) {
  case 'missing-permission': …  // Rolle fehlt
  case 'not-found':          …  // Objekt weg oder unsichtbar
  case 'validation-failed':  …  // violations ins Formular
  default:                   …  // allgemeine Meldung
}

Schlüssel aus der Persistenz sind in Großbuchstaben geschrieben (CDMS_TENANT_REQUIRED), die übrigen klein mit Bindestrich (missing-id). Für den Client ist das egal: Vergleiche den Schlüssel Zeichen für Zeichen, so wie er ist.

Drei Formen von Fehlerkörpern

Nicht jede Ablehnung kommt von CDMS selbst. Die Filterkette von CIAS läuft vorher und antwortet in eigener Form, manche Ablehnungen haben gar keinen Körper.

Mehr zu den Ablehnungen der Filterkette unter Zugriff ohne Token und 401, 403 oder 404?.

Die Validierung: violations

Nur ein Validierungsfehler hat eine Liste violations. Jeder Eintrag nennt das Feld mit seinem Pfad und die verletzte Regel:

POST /api/rest/crm/customer/create
{ "data": { "name": "" }, "response": ["id"] }

{
  "error": "ApiValidationException",
  "messageKey": "validation-failed",
  "code": "422",
  "layer": "API",
  "violations": [
    { "field": "name",  "rule": "cannot-be-empty" },
    { "field": "email", "rule": "cannot-be-null" }
  ]
}

Wie du die Einträge den Formularfeldern zuordnest, steht unter Validierungsfehler ins Formular bringen. Welche Regeln es gibt: Validierung.

Der Sonderfall: 200 in Fehlerform

Nach einem create im Modus LENIENT kann das Anlegen gelingen und nur das Zurücklesen scheitern. Dann kommt Status 200, aber ein Körper in Fehlerform mit der id des neuen Objekts:

{
  "error": "CreateSucceededReadFailedException",
  "messageKey": "CDMS_CREATE_SUCCEEDED_READ_FAILED",
  "code": "200",
  "layer": "system",
  "id": "5a2b…"
}

Das Objekt existiert.
Die id merken und später lesen,
NICHT noch einmal anlegen.

Siehe Anlegen und Zurücklesen: STRICT oder LENIENT.

So wertet ein Client aus

Fallen

Wie es weitergeht

• Welcher Status was bedeutet: Landkarte der Statuscodes
• Die drei häufig verwechselten Codes: 401, 403 oder 404?
• Die Hülle einer Erfolgsantwort: Das Antwortformat