Return HTTP 500 errors as JSON instead of HTML #63
Description
Requests that result in an HTTP 500 Internal Server Error status code return HTML even if the client is expecting to receive a JSON response. A standard JSON error response format should be adopted to be sympathetic to client error handling code.
Why?
When the server returns an error, the client (React front end, mobile app, CLI, etc.) will want to parse that error and take appropriate action. In some cases this will be displaying a message to the user, in other it may be retrying the request or logging the error. If the client is expecting to parse a JSON response and it receives HTML it will fail to parse details of the error.
Why now?
If we introduce inconsistencies in the way the server responds with errors, we make it difficult to write clients. Clients become increasingly complex to handle these inconsistencies and it gets harder to retrofit consistency.
Cost of doing nothing?
In the case of a HTTP 500 Internal Server Error clients could look at the HTTP status code in the response and decide not to parse the response body. This workaround would avoid the need for complex error handling logic, but would reduce the information that clients could determine about the cause of the error.