This post is a collection of a few things I needed to clear up (to myself or others) about HTTP Status Codes while building a RESTful API. It might not make sense for an architectural style that does not rely that much on the HTTP specification. Intro TL;DR: It is probably safe to say that most (HTTP-based) web applications and services design their server APIs to follow REST guidelines to some extent. The ones that don’t either build their API as exclusively function calls over HTTP (RPCs), or use an architectural style that introduces an extra layer of abstraction that enables additional, more complex features than what the standard HTTP protocol offers (e.g. GraphQL, SOAP). All of those don’t rely that much on HTTP functionalities. Most use only and , or just requests, and represent their responses with the basic response codes. Some even represent client errors as a successful HTTP request because the error handling is done in another layer of the application. Personally, there is nothing I hate seeing more in the Network tab than a request which is labeled as but has an error in its payload, but for some architectures that is a valid approach. GET POST POST x00 200 Keeping all of that in mind, this post will focus on HTTP response status codes from the perspective of building a RESTful API. Additionally, I will not be going into the nitty-gritty of every response status that exists or explain all the cases when a certain status should or should not be used. If you’re searching for a good overview of all the status codes, I advise checking out MDN’s on the topic. My goal is to capture some common mistakes and sources of confusion that spark discussions, PR rejections, and frantic googling by my coworkers and myself. page When in doubt, stick to the basics Before I start with specific examples, I would just like to note that there is nothing wrong with using only the base status codes to represent your responses if you are unsure what to use. All of the other ones are just extensions of those that were introduced to cover common use cases, such as wasting days on building a really creative page for 404 errors. x00 …but… While the status codes are the basic ones a few others are really common and should be used when the situation calls for it. Not using them in these situations can cause frontend developers to be unsure what exactly happened. This sometimes means implementing extra logic or doing additional requests to check the status of a resource which could have been determined if a more exact status code was used. x00 If a resource has been created on the target collection use . While a response on such an endpoint should be obvious, if your system features some kind of “upsert” or “soft delete reactivation” logic for any resource, receiving instead of can cause confusion if something other than a standard “create” happened. 201 (Created) 200 200 201 If something does not exist on the target route, please return . A base error can cause a developer to retry or search for the bug in all the wrong places, especially if it’s a or request. There is nothing worse than triple-checking your request body trying to figure out what you did wrong and then discovering that the target object never existed in the first place. 404 (Not Found) 400 PUT DELETE Operation (probably) successful but not finished This is the textbook example of when to use . It is usually used for long operations that you don’t want the client to wait for to finish, or operations that depend on an external service which you do not have control over when it is executed (SMS and other messaging services are a good example here). 202 (Accepted) This response code basically says to the client “listen, you’ve done good on your end, you can’t count on how this will go, check back on the resource later”. To a developer, this is useful because it makes them aware of the fact that an error can still happen in the processing, so the request is still a good candidate to check while error hunting in case a resource validation isn’t fully implemented or there are parts of the system (external services you pay big money for) prone to having issues. 401 vs. 403 A lot of confusion arises between and . If you got it right the first time great for you, but I’ve seen a project have to refactor its auth middleware 2-3 times because of these (mostly because it used an error library that has an error class called representing a 403 status, causing a lot of mixups with the class). 401 (Unauthorized) 403 (Forbidden) NotAuthorizedError Unauthorized Long story short: is the authentication error, thrown if the client needs to go through some login process and add those credentials to the request. 401 is the authorization error, thrown if the client has the login credentials, but does not have the correct role or set of permissions to execute an operation on or view a resource. 403 A side note on this one, that are available to different users. You can handle them the same way on the frontend if you want, but for the sake of your testers and developer colleagues, tell them if they are missing a permission. It makes stuff much more clear. Honestly, I’d advise showing the difference between and to the end-user as well because it makes bug reports a lot faster to solve. don’t use 404 to “hide” resources 404 403 When to use 409 (Conflict) has a nice name that can mean a lot of things for a developer. When a developer discovers the existence of this status, they will most probably use it in the wrong use case. This response is clearly defined to be used if there is a state mismatch between the client request and server state. 409 (Conflict) In practice, this means there isn’t a locking mechanism implemented on a resource, and two or more clients can open the same resource for edit at the same time. Client A submits its updates via a request which successfully updates the target resource, while client B is still on the edit screen. Client B sends a request to update the resource, but the server notices some inconsistencies between the resource in the request and the server’s new (updated by client A) resource. The server then can’t or won’t update the resource but will prompt the user to try again by sending a error. And that’s it, that’s the use case for this error code, no other types of conflicts should be represented by this status. PUT 409 You can be a bit more strict or liberal on what counts as “state” (e.g. what data subset is important for the request and which can be safely ignored), but an error indicating that there is a conflict between resource A and resource B in some unique property (e.g. they have the same ID property) isn’t a error but a standard . This example might seem a bit out of the blue, but the name “Conflict” can cause developers to think that the status is a good way to represent such an error. Remember, , nothing more. 409 400 (Bad Request) the 409 status only relates to state conflicts between server and client on the (same) target resource If you ever need or want to implement some kind of optimistic concurrency control for a resource, this status code is perfect for representing error responses in case of a rollback. What is 204 (No Content) I saved this one for last because a discussion about this response code is what sparked the idea for writing this whole thing. The ) response code is pretty simple. It’s used as a successful response for update (usually ) requests, it returns no body, and indicates to the client that the edits to the target resource have been saved and that the user can continue with what they were doing, i.e. the client can and remain on the same (edit) page. This response is the default option for implementing a “save and continue” mechanism where the client can treat its own resource state as in sync with the server after saving. 204 (No Content PUT The key characteristic of this response status is that it must not have a response body, that’s why it’s called “No Content”. This is great to improve performance while working on a large edit form where you can save changes mid-way. Not having to return the entire resource on every save can reduce response time by skipping data serialization and deserialization, reducing the response size to practically nothing, and potentially skipping some extra server-side fetch logic (e.g. database calls) for data needed only for building the resource view model. However, because there is no response body representing the updated resource, the assumption is that the client’s resource state is completely correct and in sync with the server’s resource state. Therefore, If this requirement cannot be met, you should use a standard response status with the changed resource described in the response body. Otherwise, the client can assume that its state is in sync with the server, and at that point, you’re just asking for all kinds of trouble. for a server to return 204 , the server MUST accept all the edits exactly as the client sent them in the request. 200 Summary I hope I’ve cleared up some confusion you might have had with the described status codes, or that I’ve helped you to make a decision about something you were unsure about using. If you’re still confused about something or wish to know more, I highly encourage you to check out MDN’s on HTTP response status codes. If that does not help, check out the RFC linked on each of the codes’ pages, they are a lot more readable than their design (or lack thereof) gives off. page Also, these rules exist for developers to utilize built-in web mechanics (such as caching), maintain consistency, and make API usage more readable and easier. The last point is extra important APIs open to external systems. However, if you have a good reason for breaking some rule, then do it. Just note explicitly what is happening in your documentation and inform your colleagues why you made this design decision. And finally, the real summary of the points in this post: use the base statuses when unsure x00 new resource => 201 no resource => 404 request good, but operation not done => 202 missing credentials => 401 wrong role / missing permission => 403 don’t use instead of 404 403 the target resource was updated (by someone else) while editing => 409 there is no use case for other than the one above 409 resource successfully updated, no need for body => 204 don’t use if the client state can become inconsistent 204 Previously published at https://nuntius.hashnode.dev/is-this-the-right-http-response-code
