API/Transitions.md

@@ -250,15 +250,104 @@ NOT YET DOCUMENTED
 
 # Errors
 
+When a transition fails, an error message is returned, it looks like this:
+
 ```json
+{
+  "error": {
     "error": {
       "involvedAttributes": [
-        null
+        "parent"
       ],
-      "entity": null,
-      "module": null,
-      "errorDescription": "unexpected_backend_error",
-      "errorType": "SYSTEM",
-      "errorID": 429
+      "entity": "unit",
+      "errorType": "REQUIRED",
+      "errorDescription": "required",
+      "errorID": "1624",
+      "module": "core"
+    },
+    "hint": {
+      "requestBody": {
+        "name": "{{name}}",
+        "unit_type": "{{unit_type}}",
+        "parent": "{{parent}}",
+        "is_titular": "{{is_titular}}",
+        "description": "{{description}}"
+      },
+      "description": "Neue Unit.",
+      "invocationVerb": "POST",
+      "id": 349,
+      "preStateID": null,
+      "name": "site_admin_create",
+      "postStateID": null,
+      "category": "create",
+      "postState": null,
+      "requestBodyContentType": "application/json; charset=UTF-8",
+      "label": "neu",
+      "attributes": {
+        "is_titular": {
+          "required": false,
+          "name": "is_titular"
+        },
+        "description": {
+          "required": false,
+          "name": "description"
+        },
+        "parent": {
+          "name": "parent",
+          "required": true
+        },
+        "unit_type": {
+          "required": false,
+          "name": "unit_type"
+        },
+        "name": {
+          "required": true,
+          "name": "name"
+        }
+      },
+      "invocationUrl": "/data/core/unit/transitions/site_admin_create",
+      "preState": null
     },
+    "db_reply": {
+      "errorCode": 1624
+    },
+    "message": "the database returned an error",
+    "path": "data/core/unit/3/transitions/site_admin_create",
+    "http_code": 400
+  }
+}
 ```
+
+The `error->error` entry has details of what type of error it is and additional information like which attributes are involved.
+
+## errorType
+
+These are the possible error types:
+
+### COMPOUND
+
+Attributes have to conform to a certain operator (e.g. equal).
+
+### CUSTOM
+
+A custom error defined for a project.
+
+### REFERENTIAL
+
+A reference is not found.
+
+### REGEXP
+
+An attribute does not conform to a regex.
+
+### REQUIRED
+
+One or more attributes are required.
+
+### UNIQUENESS
+
+One or more attributes should be unique but already exist in the database.
+
+### SYSTEM
+
+Various system errors, with `429 | unexpected_backend_error` being equivalent to an internal server error.
\ No newline at end of file