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. CIAS antwortet in genau derselben Form.

Die Antwort enthält keinen Satz für Menschen, sondern einen Schlüssel. Den Text, den der Benutzer sieht, macht dein Frontend daraus, in seiner Sprache.

Eine Fehlerantwort, beschriftet

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

{
  "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 Modellname, ein Rollenname oder eine id. Werte, die du in Feldern oder Filtern mitschickst, stehen nie darin.

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
}

Alle Schlüssel von CDMS sind klein und mit Bindestrich geschrieben, etwa tenant-required oder missing-id. 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. Sie antwortet in derselben Form, ihr Schlüssel beginnt mit cias.authentication.. 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"] }

{
  "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:

{
  "messageKey": "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