How should an a REST API handle HTTP 415 ?

Skip to first unread message


Oct 18, 2018, 9:52:12 AM10/18/18
to API Craft
How should an a REST API handle HTTP 415 ?



sune jakobsson

Oct 19, 2018, 4:15:47 PM10/19/18
This occurs when the server is unable to match the requested content typ. It really does not have anything to do with the API it is merely an indication that the server does not support the requested content type.

You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to
Visit this group at
For more options, visit

Dietrich Schulten

Oct 20, 2018, 4:53:42 AM10/20/18
Following, HTTP 415 indicates to the client that it has sent a payload which cannot be processed with the requested method on the given resource, because the media type of the payload is not suitable. Like, you sent a picture when plaintext was expected.

A rest api should respond with 415 if a client makes this kind of error. The API may offer a media type with support for hyperlinks which informs the client what it is supposed to send to make life easier for the client (collection+json, uber, hal-forms, siren, hydra, hyper-json-schema or of course html), or it could indicate a profile to overlay an existing mediatype with additional semantics by sending a profile link header, where the expected mediatypes of request bodies could be part of the profile description.

Your question might also mean, how should a client handle a 415 response. Sometimes it just failed to send a Content-Type header matching the payload. 

If an api uses no hyperlinks and no profile link header, your only hope is some out-of-band documentation, i.e. the api's website or a swagger page.

Best, Dietrich

Reply all
Reply to author
0 new messages