Hey Peter,

I think that in complex API, the semantic meaning of HTTP status code is very restricting and often abused.

Take the 409 status code you used to communicate an email address already exsists in the database (I’m ignoring the potential phishing here…) — I think this could best be communicated as a 400 error code with the payload you added.

Using 409 intead of 400 has no additional value over what is already in the payload (error: EMAIL_ALREADY_EXISTS) other than burdening the client with checking multiple error codes in each response.

I had to implement a payment API a while back and I found that the existing HTTP status codes are not sufficient to comuunicate all types of errors. After a while I found my self using exotic status codes such as 402 and 423 (I’m sure you never encountered those). In this case (and almost all other API’s I implemented since then) I used an RPC style API.

For internal API’s, such as one between a client and a server, I beleive RPC is much more flexible and maintainable. For a real world example you can take a look at Slack WEB API.

Having said that, I think the article is excelent!

Haki.