REST API Status Codes: From Chaos to Clarity
HTTP status codes are like the superheroes of API communication. They swoop in to save the day by indicating the outcome of a client's request. No more decoding mysterious messages in each response! With standardized response codes, developers can easily understand what's happening.
Enter Open API specifications (formerly Swagger), the caped crusader of API documentation. It covers everything from endpoints to request-response formats, and yes, even those trusty HTTP status codes.
Now, let's unleash the power of HTTP status codes that your dev teams should know:
Response codes are grouped in five classes:
These status codes are defined by RFC 9110.
Note: If you receive a response that is not in this list, it is a non-standard response, possibly custom to the server's software.
HTTP status codes don't have to be dull and boring. They can add a dash of excitement and playfulness to your API interactions. Enjoy the journey with these fun status codes!
Cheat Sheet
To learn more, continue further...
Information responses
100 Continue: Keep it going, champ! The server says, "Hey, you're doing great! Keep sending that request, or ignore me if you're already done."
101 Switching Protocols: Hold on to your hats! The client requested an upgrade, and the server says, "We're switching to a whole new protocol. Get ready for an exciting ride!"
102 Processing (WebDAV): Patience, young grasshopper! The server received your request and is hard at work processing it. But hold tight, there's no response available just yet.
103 Early Hints Experimental: Sneak peek alert! This status code is like a movie trailer. The server sends it along with the Link header, giving you a hint of what's to come. Meanwhile, your web browser starts preloading resources, getting ready for the grand response reveal.
Successful responses
200 OK: Congratulations, you did it! Your request succeeded, and the server is happily responding with a "success" message. But wait, the meaning of "success" depends on the HTTP method you used:
201 Created: Boom! You nailed it! Your request was not only successful but also resulted in the creation of a brand new resource. It's like the server is saying, "Bravo, creator!"
202 Accepted: Hold on a sec! The server received your request, but it's not ready to take action just yet. It's like putting your request on a to-do list. There's no immediate response indicating the outcome, so you might have to wait a bit or check back later. Patience is key!
203 Non-Authoritative Information: Trust but verify! The server is responding with information that might not be exactly the same as the original source. It's like having a backup or a mirror of the resource. Usually, the 200 OK response is preferred, unless you're dealing with mirrors or backups.
204 No Content: Hey, heads up! There's nothing to send back in response to your request, but the headers are still valuable. It's like receiving a message without any text but with important subject lines. Update your cached headers and carry on!
205 Reset Content: Time to hit the reset button! The server wants you to reset the document that initiated this request. It's like giving you a fresh start, wiping the slate clean.
206 Partial Content: Just a piece of the pie! This code pops up when you request only a specific part of a resource using the Range header. It's like ordering a single slice of pizza instead of the whole pie.
207 Multi-Status (WebDAV): Whoa, we've got multiple resources to deal with! This code is like a team huddle, conveying information about multiple resources. It's handy in situations where multiple status codes might be appropriate. Go team!
208 Already Reported (WebDAV): No need to repeat ourselves! This code helps us avoid redundancy. It's used inside a response element to avoid listing the same collection's internal members multiple times. Efficiency at its finest!
226 IM Used (HTTP Delta encoding): Time for a magical transformation! The server has fulfilled your GET request for the resource, and the response represents the result of one or more instance-manipulations applied to the current instance. It's like witnessing the result of a magical spell on the resource.
Redirection messages
300 Multiple Choices: Choices, choices everywhere! The server is presenting you with multiple options to choose from. It's like having a menu with different possibilities. So go ahead, pick one that tickles your fancy! HTML links are recommended to make the selection process easier.
301 Moved Permanently: Time for a change of scenery! The requested resource has found a new home, and it's not planning on moving back. The server kindly provides the new URL in the response. Update your bookmarks and follow the server's lead.
302 Found: Temporary relocation in progress! The URI of the requested resource has been temporarily changed. It's like the server saying, "Hey, we're over here for now, but we might move again in the future." So keep an eye out for further changes. The same URI should be used for future requests, just in case they decide to move back.
303 See Other: Follow the signs! The server wants you to redirect your request to another URI using a GET method. It's like a friendly pointer saying, "Hey, what you're looking for is over there. Go ahead and GET it!"
304 Not Modified: Ah, the power of caching! The server is telling you that the response hasn't been modified since you last fetched it. Your trusty client can continue using the same cached version of the response. No need to fetch it again, it's still fresh!
305 Use Proxy (Deprecated): Time for a blast from the past! This code was used in older versions of the HTTP specification to indicate that a proxy must be used to access the requested resource. But alas, it has been deprecated due to security concerns. Let's keep it in the museum of HTTP history.
306 unused: Shhh... don't disturb! This response code is like an empty room. It's reserved but no longer used. It had its moment in a previous version of the HTTP/1.1 specification, but it's now peacefully retired.
307 Temporary Redirect: Follow the same path! The server wants you to redirect your request to another URI, using the same method you used in the previous request. It's like saying, "Hey, we moved, but don't change your method of getting here. If you used POST before, keep using POST!"
308 Permanent Redirect: No turning back now! The resource has permanently settled in a new location. The server lets you know the new URI through the Location: HTTP Response header. It's like a firm decision, similar to the 301 Moved Permanently code. Remember, if you used POST before, stick with POST!
Recommended by LinkedIn
Client error responses
400 Bad Request: Uh-oh, something went wrong! The server received a request it couldn't understand or process due to a client error. It's like speaking gibberish to the server or taking a detour through a confusing maze. Make sure your request is properly formatted and routed!
401 Unauthorized: Hold on, who goes there? The server requires authentication before granting access to the requested resource. It's like a bouncer at a fancy club, asking for your ID before letting you in. Authenticate yourself, and the doors will open!
402 Payment Required (Experimental): Prepare for a surprise twist! This code was reserved for future use, possibly for digital payment systems. However, it's a rare sighting, and no standard convention exists for its usage. It's like stumbling upon a hidden treasure chest that hasn't been opened yet.
403 Forbidden: Access denied! The server is refusing to fulfill your request because you don't have the necessary access rights. It's like being locked out of a top-secret facility. Unlike 401 Unauthorized, the server knows exactly who you are but won't grant you access. Sorry, no entry!
404 Not Found: Lost in the digital wilderness! The server couldn't find the requested resource. It's like wandering down an unknown path and realizing you're in uncharted territory. In an API, it can also mean that the endpoint is valid, but the specific resource you're looking for doesn't exist. Keep searching, explorer!
405 Method Not Allowed: Oops, wrong approach! The server recognizes the request method you used, but it's not supported for the target resource. It's like trying to open a locked door with the wrong key. Double-check the allowed methods and choose the right one!
406 Not Acceptable: Sorry, no matches found! The server performed content negotiation but couldn't find any content that meets your criteria. It's like looking for a specific item in a store, but they don't have it in stock. Adjust your requirements, and maybe you'll find a perfect match!
407 Proxy Authentication Required: Time for double authentication! Similar to 401 Unauthorized, authentication is needed, but this time it must be done through a proxy. It's like having to prove yourself twice to gain access. Show your credentials to the proxy, and you'll be one step closer to your destination!
408 Request Timeout: Tick-tock, time's up! Some servers send this response when they detect an idle connection and want to shut it down. It's like a server reminding you, "Hey, we're still here, but let's end this unused connection." It's a signal to keep things efficient and tidy.
409 Conflict: Clash of requests! The server encountered a conflict with the current state of the resource due to a request. It's like two people fiercely fighting over the last piece of cake. Resolve the conflict and try again!
410 Gone: Vanished into thin air! The requested content has been permanently deleted, leaving no forwarding address. It's like a magic trick where something disappears completely. Clients should remove any traces of the resource, as it's gone for good. Poof!
411 Length Required: Measure twice, request once! The server rejected the request because the Content-Length header field wasn't defined, and the server requires it. It's like forgetting to specify the length of a package you're sending. Provide the necessary details, and your request will be back on track!
412 Precondition Failed: Expectations not met! The client specified certain conditions in its headers, but the server couldn't meet them. It's like making a deal with specific requirements, but the other party can't fulfill them. Reevaluate your conditions, and let's try again!
413 Payload Too Large: Whoa, too much to handle! The request entity you sent is larger than what the server allows. It's like trying to squeeze an elephant through a mouse hole. The server might close the connection or provide a Retry-After header field. Trim down the payload, and try a lighter load!
414 URI Too Long: Longest URL contest winner! The URI you provided is longer than what the server is willing to interpret. It's like trying to recite an entire novel as a website address. Shorten the URI, and you'll fit within the server's limits!
415 Unsupported Media Type: Sorry, wrong format! The server doesn't support the media format of the requested data. It's like speaking a language the server doesn't understand. Check the supported formats and send the data in a compatible type!
416 Range Not Satisfiable: Out of reach! The range specified in the request's Range header field cannot be fulfilled. It's like reaching for something that's outside of your grasp. Make sure your range falls within the target's data size!
417 Expectation Failed: Sorry, expectations not met! The server couldn't meet the expectation specified in the Expect request header field. It's like expecting a surprise party but ending up with a regular gathering. Adjust your expectations, and let's try again!
418 I'm a teapot: Time for some fun! The server playfully refuses an attempt to brew coffee using a teapot. Yes, you heard it right! It's like asking your teapot to make you a cappuccino—it's just not going to happen. Enjoy this whimsical status code and embrace the lighthearted side of the web!
421 Misdirected Request: Lost in translation! The request was sent to a server that can't generate a response for the combination of scheme and authority included in the request URI. It's like sending a letter to the wrong address. Make sure your request is properly directed to the right server!
422 Unprocessable Content (WebDAV): Good effort, but... The request was well-formed, yet it couldn't be followed due to semantic errors. It's like writing a grammatically correct sentence that doesn't make any sense. Review your request and address the semantic errors!
423 Locked (WebDAV): Access denied, resource locked! The resource you're trying to access is currently locked. It's like encountering a "Do Not Enter" sign on a door. Wait for the lock to be removed or seek an alternative resource.
424 Failed Dependency (WebDAV): Oops, dependency failure! The request failed because it relied on a previous request that didn't succeed. It's like building a tower of blocks where one block is missing. Resolve the dependency issue, and your request will stand strong!
425 Too Early (Experimental): Not so fast! The server is unwilling to process a request that might be replayed. It's like hesitating to take action because of the possibility of repeating a previous mistake. Take a breath, pause, and proceed cautiously.
426 Upgrade Required: Time for an upgrade! The server refuses to perform the request using the current protocol but is willing to do so if the client upgrades to a different protocol. It's like telling you, "Hey, to proceed, you need to level up your game." Pay attention to the Upgrade header in the response for the required protocol.
428 Precondition Required: Conditions, conditions! The origin server requires the request to be conditional. It's like saying, "I'll give you what you want, but only if certain conditions are met." This response helps avoid conflicts when multiple clients try to modify the same resource simultaneously.
429 Too Many Requests: Slow down, speed racer! The user has sent too many requests within a given timeframe, exceeding the rate limit. It's like entering a buffet and devouring all the food in seconds. Pace yourself and respect the server's limits!
431 Request Header Fields Too Large: Hold your horses, headers! The server is reluctant to process the request because its header fields are too large. It's like trying to fit an entire library into a single backpack. Trim down your headers, and try again!
451 Unavailable For Legal Reasons: Stop right there, legality involved! The user agent requested a resource that cannot be legally provided, perhaps due to censorship or legal restrictions. It's like asking for something forbidden by the authorities. Respect the legal boundaries and seek alternative resources.
Server error responses
500 Internal Server Error: Uh-oh, the server is having a meltdown! It has encountered a situation it doesn't know how to handle. It's like a chef in the kitchen who suddenly forgot how to cook. Hang tight while the server figures out what went wrong.
501 Not Implemented: Sorry, that request method is not on the menu! The server doesn't support the requested method and can't handle it. The only methods servers are required to support are GET and HEAD. It's like asking a magician to perform a trick they haven't mastered. Stick to the supported methods for now!
502 Bad Gateway: Oops, the server played a game of telephone and got an invalid response! It's working as a gateway to get the necessary response, but received something it couldn't understand. It's like passing a message along a line of friends, only to end up with a garbled message. Check the communication lines and try again!
503 Service Unavailable: Time for a server siesta! The server is not ready to handle the request. It might be down for maintenance or overwhelmed with too much traffic. Along with this response, a friendly page explaining the issue should be sent. It's like finding a "Be Back Soon" sign on a shop's door. Wait patiently or come back later!
504 Gateway Timeout: The server is playing hide-and-seek, but it's taking too long to respond! It's acting as a gateway but couldn't get a response in time. It's like waiting for a friend to show up, but they're running late. Patience is key, but if they take too long, you might need to find another way.
505 HTTP Version Not Supported: Sorry, wrong generation! The server doesn't support the HTTP version used in the request. It's like speaking a language from the future that hasn't been invented yet. Check your HTTP version and make sure it's compatible!
506 Variant Also Negotiates: Oops, the server got tangled in its own web! There's an internal configuration error, and the chosen variant resource is trying to negotiate content itself instead of being an endpoint in the negotiation process. It's like a confused actor stealing the director's role. Untangle the configuration and clarify the roles!
507 Insufficient Storage (WebDAV): Running out of space! The server can't perform the requested method on the resource because it's unable to store the necessary representation. It's like trying to fit a giant elephant into a tiny shoebox. Clear up some storage space, and try again!
508 Loop Detected (WebDAV): Caught in an infinite loop! The server detected a never-ending loop while processing the request. It's like a whirlpool that keeps pulling you in deeper. Break the loop and find a different path!
510 Not Extended: Hold your horses, more information needed! The server requires further extensions to fulfill the request. It's like ordering a pizza without specifying the toppings. Provide the necessary extensions, and the server will happily oblige!
511 Network Authentication Required: Time to show your ID! The client needs to authenticate to gain network access. It's like trying to enter a secret club without the proper credentials. Authenticate yourself, and the network will welcome you in.
Phew! That was quite a ride through the world of server errors and unexpected situations. Remember, each status code tells a different story about the interaction between the client and the server. Enjoy your adventures in the realm of web communication!
Top Gun 🚀
1ynice post