Add API errors to API Docs

[Cryptophobia]

From @Joshua-Anderson on June 20, 2016 18:53

Right now, we don't document any of the errors that the API can return on an request, making it difficult for people trying to build in error handling for the api.

Even if we don't document every error, just documenting the format of the error messages makes it easier for people to parse them.

For example: POST /v2/auth/register/ with no body returns 400 with a body of

{
  "username": [
    "This field is required."
  ],
  "password": [
    "This field is required."
  ]
}

Copied from original issue: deis/workflow#334

[Cryptophobia]

From @bacongobbler on October 12, 2016 16:18

I'm pretty sure we did not decide to go through with this because of the amount of ambiguous errors that can pop up not only from the ones we define, but from DRF or from python itself. Do you agree, @Joshua-Anderson?

[Cryptophobia]

From @Joshua-Anderson on October 12, 2016 20:59

I'm not sure defining every error is feasible, but defining at least some of the common errors can be helpful. There are a several errors that can come up through no fault of the API client itself, like the all apps must be transferred before deleting a user error, the API clients should know how to handle.

The big problem is that we have several error response formats (since python, DRF, and deis errors all look different), so it's hard for a client to assume what an error message will look like.