Best Practice: HTTP Status Codes

[#1]

I have a service which returns students, by locker number. Depending on the query, my service may return:

• One student
• Multiple students (meaning the locker is shared & you should probably provide a locker-shelf number as well)
• No student
• Error processing your request (bad locker number?)

I've seen some APIs leverage the HTTP status codes to communicate resource state. Eg:
20x for 'one student'
30x for 'multiple students'
40x for 'no student'
50x for 'error'

Do modern developers expect this? Or.. should status codes speak only to the HTTP response state, rather than hinting at payload? I'm looking for some pros/cons, based on what you've seen work for other successful API programs.

[ozanseymen]

My opinions:

20x for 'one student' - fine.

30x for 'multiple students' - couldn't understand why this is a redirection. "Modern developers" will expect a redirection here.

40x for 'no student' - if this is a search/find operation, 200 should be the result. If this is a resource GET, then 404 might also work.

[ssvaidyanathan]

+1

Keep it simple

[Former Community Member]

+1 @Ozan Seymen

Keeping it simple:

A search with no results is till 200. Multiple results are still 200.

A get can return 404 if retrieving a student id: /students/id.

A get can return 404 if retrieving students like: /lockers/id and the id does not exist.

One additional possibility if you like to rely on http codes:

206 - for partial content. i.e., you could not give the full list. This can also be handled in the payload by having a pagination section.

[ceber]

I suggest sticking with the spirit of the spec. 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error.

When I run into an API that gets "clever" with the response codes I get worried.

In the case above, I'm not sure why you would need to return a non-200 code for a multiple student response. What value does it provide? The content of the response should be enough to show there are more than one students returned and can give all the info the client needs to get to the desired student (or next action).

[kurtkanaskie]

Agree on not abusing 3xx for multiple students.

I've seen clients choose to differentiate error codes:

40x for proxy related errors

420 for "Internal API" errors (e.g Edge ==> Internal API ==> Backend SOR

50x for Backend errors

[ceber]

Personally I don't like this. I can see how the API team might consider the proxy a client of the backend and want to put some sort of "client" error response in there, but to me that's counter to the outside-in thinking encouraged by the digital value chain. As the API consumer when I see a 4xx I expect I have a problem in my control. I asked for something that isn't there, I used an incorrect content-type, method, etc. I'd vote for using a range in the 5xx side instead.

Just my 2 pennies. 😉

[kurtkanaskie]

Yes, I agree, as @Carlos Eberhardt stated 4xx for client errors. In my example, 420 was a "client" error that was detected outside of the Edge proxy but still before it hit the real backend.

The customer wanted to differentiate between the two. Edge detected invalid requests 400, internal API detected business rule violation 420 (e.g. transaction not allowed, dollar amount exceeded limit).

In hindsight, perhaps it would have been better to use 400 and differentiate with sub-status codes.

[ceber]

Isn't 420 "Enhance your calm" as used by twitter when you hit a rate limit? Historically, maybe? I don't think they do that anymore.

I think you should always respect internet history. 😉

That means don't use 418 I'm a Teapot either.

[kurtkanaskie]

Here's and oldy-but-goody article: https://apigee.com/about/blog/technology/restful-api-design-what-about-errors