Example Error Objects

bf4 · bf4 · commit d985b6db5b1f · 2015-08-05T14:29:13.000-05:00
diff --git a/examples/index.md b/examples/index.md
@@ -126,3 +126,119 @@ Content-Type: application/vnd.api+json
 for readability. In practice, these characters must be percent-encoded, as
 noted in the base specification.
 
+## Error Objects
+
+Examples of how [example objects](http://jsonapi.org/format/#error-objects) work.
+
+### Responses to failed resource creation:
+
+Response with one error object:
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/vnd.api+json
+
+{
+  "errors": [
+    {
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "is too short"
+    }
+  ]
+}
+```
+
+Response with status:
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/vnd.api+json
+
+{
+  "errors": [
+    {
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "is too short"
+    },
+    {
+      "status": "422",
+    }
+  ]
+}
+```
+The only uniqueness constraint on error objects in a response is the `id` field.
+Multiple errors on the same attribute may be described by an error object
+for each error.
+
+Multiple errors on `first_name` attribute:
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/vnd.api+json
+
+{
+  "errors": [
+    {
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "is too short"
+    },
+    {
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "must contain an emoji"
+    }
+  ]
+}
+```
+
+If the API docs specified:
+
+> | Error Code | Title                |
+> |------------|----------------------|
+> |  123       | "too short"          |
+> |  124       | "emoji missing"      |
+
+Multiple errors on `first_name` attribute, with error "code":
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/vnd.api+json
+
+{
+  "errors": [
+    {
+      "code":   "123",
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "is too short"
+    },
+    {
+      "code":   "124",
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "must contain an emoji"
+    }
+  ]
+}
+```
+
+Multiple errors on `first_name` attribute, with error code, and "title":
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/vnd.api+json
+
+{
+  "errors": [
+    {
+      "code":   "123",
+      "title":  "too short",
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "is too short"
+    },
+    {
+      "code":   "124",
+      "title":  "emoji missing",
+      "source": { "pointer": "data/attributes/first_name" },
+      "detail": "must contain an emoji"
+    }
+  ]
+}
+```
