Ensure JSON:API spec compliance for exceptions

[wagenet]

The relevant JSON:API spec is here https://jsonapi.org/format/.

Some key items:

400

• If an endpoint does not support the include parameter, it MUST respond with 400 Bad Request to any requests that include it.

• If a server is unable to identify a relationship path or does not support inclusion of resources from a path, it MUST respond with 400 Bad Request.

• If the server does not support sorting as specified in the query parameter sort, it MUST return 400 Bad Request.

• If a server encounters a query parameter that does not follow the naming conventions above, and the server does not know how to process it as a query parameter from this specification, it MUST return 400 Bad Request.

403

• A server MUST return 403 Forbidden in response to an unsupported request to create a resource with a client-generated ID.

• A server MAY return 403 Forbidden in response to an unsupported request to create a resource.

• A server MAY reject an attempt to do a full replacement of a to-many relationship. In such a case, the server MUST reject the entire update, and return a 403 Forbidden response.

404

• A server MUST return 404 Not Found when processing a request to modify a resource that does not exist.

• A server MUST return 404 Not Found when processing a request that references a related resource that does not exist.

• A server MUST respond with 404 Not Found when processing a request to fetch a single resource that does not exist, except when the request warrants a 200 OK response with null as the primary data (as described above).

• A server MUST return 404 Not Found when processing a request to fetch a relationship link URL that does not exist.
  If a relationship link URL exists but the relationship is empty, then 200 OK MUST be returned, as described above.

• A server SHOULD return a 404 Not Found status code if a deletion request fails due to the resource not existing.

406

• Servers MUST respond with a 406 Not Acceptable status code if a request’s Accept header contains the JSON:API media type and all instances of that media type are modified with media type parameters.

409

• A server MUST return 409 Conflict when processing a POST request to create a resource with a client-generated ID that already exists.

• A server MUST return 409 Conflict when processing a POST request in which the resource object’s type is not among the type(s) that constitute the collection represented by the endpoint.
  A server SHOULD include error details and provide enough information to recognize the source of the conflict.

• A server MAY return 409 Conflict when processing a PATCH request to update a resource if that update would violate other server-enforced constraints (such as a uniqueness constraint on a property other than id).

• A server MUST return 409 Conflict when processing a PATCH request in which the resource object’s type and id do not match the server’s endpoint.

415

• Servers MUST respond with a 415 Unsupported Media Type status code if a request specifies the header Content-Type: application/vnd.api+json with any media type parameters.

422

• In the responses ... with a 422 status code, 400 Bad Request would also be acceptable. (More details.) JSON:API doesn’t take a position on 400 vs. 422.

Also relevant

• When a server encounters multiple problems for a single request, the most generally applicable HTTP error code SHOULD be used in the response. For instance, 400 Bad Request might be appropriate for multiple 4xx errors or 500 Internal Server Error might be appropriate for multiple 5xx errors.

[wagenet]

We should probably write specs for these items.