From 15a977311a08507121c8f4418353bdf809f9945c Mon Sep 17 00:00:00 2001
From: David Buchmann <david.buchmann@liip.ch>
Date: Tue, 16 Aug 2016 08:35:09 +0200
Subject: [PATCH] clarify use case of error plugin

---
 plugins/error.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/plugins/error.rst b/plugins/error.rst
index eede57c..00df237 100644
--- a/plugins/error.rst
+++ b/plugins/error.rst
@@ -30,3 +30,9 @@ and the response coming from them::
             // Something has not been found
         }
     }
+
+The error plugin is intended for when an application operates with the client directly. When
+writing a library around an API, the best practice is to have the client convert responses into
+domain objects, and transform HTTP errors into meaningful domain exceptions. In that scenario,
+the ErrorPlugin is not needed. It is more efficient to check the HTTP status codes yourself than
+throwing and catching exceptions.