HTTP Response Codes and You

This blog post was originally on the Clarify blog and is captured here for historical reasons.

Proper HTTP response code usage is one of the most powerful yet underutilized aspects in web development. Most developers are familiar with the common 200 OK, the often-used 301 and 302 redirects, and the ever-annoying 404 Not Found but there are over 40 other codes that offer granularity and flexibility to API designers and their client applications.

When we designed the Clarify API, we wanted to Do the Right Thing and take advantage of the HTTP response codes. More importantly, we wanted to make sure to use each in the correct context and for the right purposes. Towards that goal, here are the most common HTTP response codes you may see while using an API along with where you’ll see them in the Clarify API:

  • 200 OK – This is generated after you successfully complete an action that doesn’t change a resource. This can be anything from reading a resource to retrieving search results.
  • 201 Created – This is generated after you create a resource with the API. Most likely this will be a new bundle or adding a track to an existing bundle.
  • 202 Accepted – This is received after you update a resource. This is only received when you update (not create) a bundle or the tracks that are part of the bundle.
  • 204 No Content – This is normally received after you delete a resource. You’ll only receive this one if you delete a bundle or its parts (tracks or metadata).
  • 301 Moved Permanently – This designates that a resource has moved and will be available at the new URI from here forward. This does not currently appear in the Clarify API.
  • 301 Moved Temporarily – This designates that a resource has moved and will be available at the new URI for a while but will eventually return to the original URI. This does not currently appear in the Clarify API.
  • 400 Bad Request – This simply means that your request failed because it was incorrect for some reason. Some APIs will give you additional information like why it failed but you can’t count on that. In our case, we simply return the 400 without much additional context. This is somewhere we could improve.
  • 401 Authentication Required – This designates that – before the action is attempted – authentication is required. It doesn’t imply that the action would or would not have worked, just that authentication is required before it should be attempted again.
  • 403 Forbidden – This means the action failed and should not be attempted again. We don’t use this in the API but there are a few places where it might make sense.
  • 404 Not Found – This means the resource you requested could not be found. We use this in the API exactly as described.
  • 500 Internal Server Error – This designates that the server itself has suffered an error. It is not designed to be part of the Clarify API but you may receive it if there is a server issue somewhere.

There are also two less common HTTP Response Codes which you might see as you use our API:

  • 409 Conflict – This response code describes that the request was unable to be completed due to a request conflict. Most likely this occurs if you are trying to update a resource which has already been updated since your last request. You will only see this from the API if you are attempting to update a bundle which has already been updated. It’s rare but can occur.
  •  415 Unsupported Media Type – An unsupported media type error occurs when you attempt to use a media type which the server does not handle or cannot understand. For example, if you attempt to load an image or pdf into the Clarify API, you’ll receive a 415 as we only handle audio and video formats.

Quite often as you’re building an API, you may discover places where a new HTTP Response Code makes sense. Don’t do it. While there is room in the standards for more codes, there are many that are reserved or otherwise defined. Most likely a better approach is to use the basic code – probably a 400 – and then decorate the error response with additional information as defined in the vnd.error specification.

Remember, with great power comes great responsibility.