Back to Docusign.com
We have a big problem with e-Signature APIs. They do NOT report error properly in a RESTful manner. We should NEVER have silent failures where the HTTP status response code states a happy 200 status, but the response body contains an error message. This is an anti-pattern, as we should never be forced to introspect a response body to look for errors and throw our own exceptions. We should be catching these as errors as either 4xx or 5xxx series errors.
The renowned Martin Fowler provides a nice Reader’s Digest condensed version of Richardson’s Maturity Model.
From https://martinfowler.com/articles/richardsonMaturityModel.html#level2
“There is another difference if something goes wrong, such as someone else booking the session.
HTTP/1.1 409 Conflict
cvarious headers]
The important part of this response is the use of an HTTP response code to indicate something has gone wrong. In this case a 409 seems a good choice to indicate that someone else has already updated the resource in an incompatible way. Rather than using a return code of 200 but including an error response, at level 2 we explicitly use some kind of error response like this. It's up to the protocol designer to decide what codes to use, but there should be a non-2xx response if an error crops up. Level 2 introduces using HTTP verbs and HTTP response codes.”
