added graphql error example and rephrased section

README.md

@@ -160,7 +160,7 @@ Read in a different language: [![CN](/assets/flags/CN.png)**CN**](/README.chines
 
 **Otherwise:** An API client might decide to crash and restart only because it received back an error it couldn’t understand. Note: the caller of your API might be you (very typical in a microservice environment)
 
-🔗 [**Read More: documenting errors in Swagger**](/sections/errorhandling/documentingusingswagger.md)
+🔗 [**Read More: documenting API errors in Swagger or GraphQL**](/sections/errorhandling/documentingusingswagger.md)
 
 <br/><br/>
 

sections/errorhandling/documentingusingswagger.md

@@ -4,7 +4,42 @@
 
 REST APIs return results using HTTP status codes, it’s absolutely required for the API user to be aware not only about the API schema but also about potential errors – the caller may then catch an error and tactfully handle it. For example, your API documentation might state in advance that HTTP status 409 is returned when the customer name already exists (assuming the API register new users) so the caller can correspondingly render the best UX for the given situation. Swagger is a standard that defines the schema of API documentation offering an eco-system of tools that allow creating documentation easily online, see print screens below
 
-If you have already adopted GraphQL for your API endpoints, chances are that your schema already contains guarantees as to what errors should look like and how they should be handled by your client-side tooling. In addition, you can also supplement them with comment-based documentation.
+If you have already adopted GraphQL for your API endpoints, your schema already contains strict guarantees as to what errors should look like ([outlined in the spec](https://facebook.github.io/graphql/June2018/#sec-Errors)) and how they should be handled by your client-side tooling. In addition, you can also supplement them with comment-based documentation.
+
+### GraphQL Error Example
+
+> This example uses [SWAPI](https://graphql.org/swapi-graphql), the Star Wars API.
+
+```graphql
+# should fail because id is not valid
+{
+  film(id: "1ZmlsbXM6MQ==") {
+    title
+  }
+}
+```
+
+```json
+{
+  "errors": [
+    {
+      "message": "No entry in local cache for https://swapi.co/api/films/.../",
+      "locations": [
+        {
+          "line": 2,
+          "column": 3
+        }
+      ],
+      "path": [
+        "film"
+      ]
+    }
+  ],
+  "data": {
+    "film": null
+  }
+}
+```
 
 ### Blog Quote: "You have to tell your callers what errors can happen"