A Comprehensive Guide to HTTP Status Codes: When and How to Use Them in API Development

22 min readSep 25, 2023

In the ever-evolving realm of web development and API design, HTTP status codes play a pivotal role in facilitating communication between servers and clients. These three-digit numeric codes, such as the familiar “404 Not Found” or “200 OK,” serve as concise messages that convey the outcome of a client’s request and the state of resources on the server. Understanding these status codes is not just a fundamental aspect of web development; it is crucial for creating efficient and user-friendly web applications.

In this comprehensive guide, we will demystify the world of HTTP status codes. We will delve into the meanings behind each code, provide relatable scenarios to make them more accessible, and explore the situations in which they should be employed. By the end of this journey, you will have a clear grasp of the significance of HTTP status codes and their practical applications in API development, equipping you with the knowledge to enhance the reliability and usability of your web services.

HTTP Status Codes Overview

HTTP status codes are three-digit numbers that indicate the result of an HTTP request. They are grouped into five classes, each serving a specific purpose:

Informational (1xx): These codes provide provisional responses and indicate that the server has received the request and is continuing to process it. The client can expect further communication.
Successful (2xx): These codes indicate that the request was successfully received, understood, and accepted. They are the most common status codes when everything goes as expected.
Redirection (3xx): These codes indicate that further action needs to be taken to complete the request. Typically, they instruct the client to redirect to a different URL or resource.
Client Errors (4xx): These codes indicate that the client seems to have made an error in the request. It could be due to invalid input, authentication issues, or insufficient permissions.
Server Errors (5xx): These codes indicate that the server encountered an error while processing the request. Server errors often result from issues on the server-side, such as server overload or misconfigurations.

Now, let’s dive into the details of some of the most commonly used HTTP status codes and when to use them in API development.

100 Continue

What it means: When you see this, it means the server is telling the client to keep going with the request or just ignore the response if the request is already done.
Imagine it like this: It’s like the server saying, “Don’t stop now, keep going with your request.”
When to use it: Use it when you want to acknowledge the client’s request and allow them to continue sending data in the request body. It’s handy for large uploads where you don’t want to interrupt the process

101 Switching Protocols

What it means: This code comes up when the client wants to change to a different communication method, and the server agrees. It’s like the server saying, “Okay, let’s talk in a different way now.”
Imagine it like this: Think of it as switching from talking on the phone to sending text messages because it’s more efficient.
When to use it: Use it when the client requests to switch to a different protocol, such as moving from HTTP to WebSocket for real-time communication.

102 Processing (WebDAV)

What it means: When you see this, it means the server got your request and is working on it, but it doesn’t have an answer for you just yet.
Imagine it like this: It’s like you ordered food, and the restaurant says, “We got your order, but it’s not ready. Please wait.”
When to use it: Use it in cases where the server needs some time to process a request, like when handling complex operations or calculations. It lets the client know that the request was received and is being worked on.

103 Early Hints (Experimental)

What it means: This one is a bit special. It’s used with a “Link” header to tell the client to start getting ready for some resources even before the server finishes preparing the full response.
Imagine it like this: It’s like a movie trailer that gives you a sneak peek of what’s coming, so you start getting excited about it.
When to use it: Use it when you want to optimize performance by giving the client a hint about resources they might need based on their initial request. This can be useful for preloading assets like images, stylesheets, or scripts to make the user experience smoother.

200 OK

What it means: The request was successful. What “success” means depends on the type of request:
For GET requests, the requested data is in the response body.
For HEAD requests, you get just the info about the data, no actual data.
For PUT or POST requests, the result of the action is in the response.
For TRACE requests, you get the request itself as received by the server.
Imagine it like this: It’s like ordering food, and you get exactly what you asked for, or you get a confirmation that your order is received.
When to use it: Use it when everything went well and you’re sending back the requested data or the outcome of an action.

201 Created

What it means: The request succeeded, and a new resource was created. Typically used after making a new thing with a POST request or updating with a PUT request.
Imagine it like this: It’s like building something new, and when you’re done, you proudly say, “Look, I’ve created this!”
When to use it: Use it when a resource is successfully created in response to a client’s request.

202 Accepted

What it means: The server got the request but hasn’t done anything with it yet. It’s like saying, “I received your request, but I’m not telling you what happens next.”
Imagine it like this: It’s like dropping your laundry off at the cleaners. They acknowledge your clothes, but you’ll have to wait for them to finish the job.
When to use it: Use it when you’ve accepted the request, but it might take some time to process, or another process/server handles it.

203 Non-Authoritative Information

What it means: The data in the response isn’t directly from the main server but from a copy, like a backup or mirror. Usually not needed unless you’re dealing with copies of resources.
Imagine it like this: It’s like reading a book from a library’s copy instead of the original book.
When to use it: Use it when you’re returning data from a copy of a resource, not the original.

204 No Content

What it means: There’s nothing to send back in the response body, but the headers might be useful. It’s like saying, “I have nothing to show you, but here are some details.”
Imagine it like this: It’s like receiving an email with an empty message but with an important subject line.
When to use it: Use it when there’s no data to send, but you want to update headers or provide some information.

205 Reset Content

What it means: Tells the client to reset the document that made the request. It’s like saying, “Start over with that thing you were working on.”
Imagine it like this: It’s like hitting the “Restart” button on your computer to clear things up.
When to use it: Use it when you want the client to reset something based on their previous request.

206 Partial Content

What it means: Used when the client asks for only part of a resource using the Range header.
Imagine it like this: It’s like watching only a part of a movie instead of the whole thing.
When to use it: Use it when the client requests only a portion of a resource, like asking for a specific part of a long video.

207 Multi-Status (WebDAV)

What it means: It’s used when you have multiple resources and need to convey different status codes for each.
Imagine it like this: It’s like sending a report with different grades for different subjects.
When to use it: Use it in situations where multiple status codes are needed for various resources involved in a request.

208 Already Reported (WebDAV)

What it means: It’s used to avoid repeating information about internal members of multiple bindings to the same collection.
Imagine it like this: It’s like providing a summary instead of listing every detail repeatedly.
When to use it: Specific to WebDAV situations where this particular scenario arises.

226 IM Used (HTTP Delta encoding)

What it means: The server used a special method to fulfill a GET request, and the response shows changes applied to the resource.
Imagine it like this: It’s like getting updates for a software application instead of downloading the entire program again.
When to use it: Use it when you’re sending back changes made to a resource as a result of a GET request, especially when using HTTP Delta encoding.

300 Multiple Choices

What it means: There are multiple ways to get what you asked for. You need to pick one, but there’s no set way to do it. Think of it like a menu with several options, and you choose what you want.
Imagine it like this: It’s like a menu with several options, and you choose what you want. Like picking your favorite flavor of ice cream.
When to use it: Use it when a request can lead to multiple responses, and the client needs to make a choice.

301 Moved Permanently

What it means: The thing you’re looking for has moved to a new place on the internet, and it’s not coming back here. We’ll give you the new address, though.
Imagine it like this: It’s like your friend moved to a new house, and they gave you their new address. You know they won’t be at the old place anymore.
When to use it: Use it when a resource has permanently moved to a new location, and you want to tell the client where to find it now.

302 Found

What it means: The thing you’re looking for is somewhere else right now, but it might come back here later. You should check here again later.
Imagine it like this: It’s like your favorite store temporarily moved to a different location in the mall, but they’ll be back in their usual spot soon.
When to use it: Use it when a resource has temporarily moved, and you expect it to come back to its original location eventually.

303 See Other

What it means: We’ve found what you wanted, but it’s somewhere else. Go to that place to get it, but use a GET request when you go there.
Imagine it like this: It’s like your teacher telling you to get a book from the library, and they give you directions to where the book is on the shelf.
When to use it: Use it when you want the client to get the requested resource at a different location with a GET request.

304 Not Modified

What it means: You’ve asked for something, but guess what? It hasn’t changed since the last time you asked for it. You can keep using your old copy; no need to get a new one.
Imagine it like this: It’s like your friend loaned you a book, and when you ask for it again, they say, “You still have the same book; no need to borrow it again.”
When to use it: Use it for caching purposes to tell the client that the resource hasn’t changed, so they can use their cached version.

305 Use Proxy (Deprecated)

What it means: In the past, we used to tell you to go through a proxy to get this, but it’s not safe anymore, so don’t do it. It’s like an old, unsafe shortcut that’s not recommended.
Imagine it like this: It’s like an old, unsafe shortcut that you used to take, but now you’re advised to take the longer, safer route.
When to use it: This one’s not used anymore due to security concerns. Avoid it.

306 Unused

What it means: This code used to mean something, but we’re not using it now. It’s just reserved in case we need it in the future.
Imagine it like this: It’s like having an empty slot on your keyboard for a button that doesn’t do anything right now, but it might have a purpose later.
When to use it: Don’t use it. It’s not used in the current HTTP specification.

307 Temporary Redirect

What it means: Like a temporary detour sign on a road, we’re telling you to go somewhere else for now, but use the same method you used before.
Imagine it like this: It’s like a roadblock that redirects you to a detour, but you’re still driving your car in the same way as before.
When to use it: Use it when you want the client to temporarily go to a different location for the resource, but keep using the same HTTP method as before.

308 Permanent Redirect

What it means: The thing you want has moved forever. Here’s the new address, and make sure you use the same method as you did before.
Imagine it like this: It’s like moving to a new house, and you tell everyone your new address. You also mention that they should still come to your new house in the same way they used to visit your old one.
When to use it: Use it when a resource has permanently moved to a new location, and you want to tell the client where to find it now, while also specifying they should use the same HTTP method.

400 Bad Request

What it means: The server can’t understand the client’s request. It’s like receiving a letter with handwriting so messy that you can’t read it.
Imagine it like this: Imagine a waiter not understanding your order because you mumbled or spoke in a language they don’t know.
When to use it: Use it when the client sends a request that’s malformed or confusing.

401 Unauthorized

What it means: The server says, “You can’t see this unless you prove who you are.” It’s like a security guard asking for your ID before letting you into a restricted area.
Imagine it like this: It’s like trying to enter a VIP party without showing your invitation.
When to use it: Use it when the client needs to provide authentication (like a username and password) to access a resource.

402 Payment Required (Experimental)

What it means: Reserved for future use. Originally meant for digital payments, but not widely used.
Imagine it like this: It’s like having a payment option on a website that’s not active yet.
When to use it: Not commonly used. Avoid unless you’re part of a system that plans to implement it in the future.

403 Forbidden

What it means: You’re not allowed to see this, even if you prove who you are. It’s like being told you can’t enter a room, no matter who you are.
Imagine it like this: It’s like trying to access someone else’s private diary; you’re not allowed, no matter what.
When to use it: Use it when the client is authenticated but doesn’t have permission to access a specific resource.

404 Not Found

What it means: The thing you’re looking for doesn’t exist. It’s like trying to find a hidden treasure that’s not there.
Imagine it like this: It’s like searching for a book in a library, but that book has never been in the library.
When to use it: Use it when the requested resource can’t be found on the server.

405 Method Not Allowed

What it means: The server knows what you want but won’t let you use that method. It’s like a vending machine that only accepts coins, not bills.
Imagine it like this: It’s like trying to open a door by pushing when you should be pulling.
When to use it: Use it when the client uses an HTTP method that’s not allowed for the requested resource.

406 Not Acceptable

What it means: The server can’t provide a response that meets the client’s criteria. It’s like asking for a specific type of pizza, and the restaurant doesn’t have it.
Imagine it like this: It’s like trying to watch a movie in Spanish, but the movie only has English subtitles.
When to use it: Use it when the server can’t fulfill the client’s request based on the specified criteria.

407 Proxy Authentication Required

What it means: Similar to 401 Unauthorized, but the client needs to authenticate through a proxy.
Imagine it like this: It’s like needing a special ticket to enter a movie theater, and you have to get it from a different counter.
When to use it: Use it when the client needs to authenticate through a proxy server.

408 Request Timeout

What it means: The server wants to end the connection because it’s not being used. It’s like hanging up the phone because no one’s talking.
Imagine it like this: It’s like a server saying, “I’ve been waiting for you to say something, but you’re not, so I’ll hang up.”
When to use it: Use it when the server wants to close an idle connection.

409 Conflict

What it means: The request can’t be fulfilled because it conflicts with the current state of the server. It’s like trying to book a seat on an already full plane.
Imagine it like this: It’s like trying to make two changes to a document at the same time, and they don’t work together.
When to use it: Use it when there’s a conflict between the client’s request and the server’s current state.

410 Gone

What it means: The requested resource has been permanently removed, and there’s no way to find it again. It’s like a book that’s been deleted from the library, and there’s no trace of it left.
Imagine it like this: It’s like visiting a website, but the page you’re looking for has been deleted, and there’s no forwarding address.
When to use it: Use it when a resource has been permanently removed from the server.

411 Length Required

What it means: The server needs to know the size of the request, but the client didn’t provide that information. It’s like ordering a pizza, but not telling them what size you want.
Imagine it like this: It’s like sending a package without specifying its weight or dimensions.
When to use it: Use it when the server expects a “Content-Length” header in the request, and it’s missing.

412 Precondition Failed

What it means: The client set conditions in its request, but the server didn’t meet those conditions. It’s like making a deal with conditions, but one side didn’t follow through.
Imagine it like this: It’s like saying, “I’ll buy this if it’s on sale,” but the item isn’t on sale, so you don’t buy it.
When to use it: Use it when the client sets conditions, and the server can’t meet them.

413 Payload Too Large

What it means: The client sent a request that’s too big for the server to handle. It’s like trying to fit a truckload of furniture into a small car.
Imagine it like this: It’s like trying to send an email with a huge attachment, but the email server can’t handle the size.
When to use it: Use it when the request payload exceeds the server’s limits.

414 URI Too Long

What it means: The client’s request URL is too long for the server to process. It’s like trying to read a web address that’s too long to fit on the screen.
Imagine it like this: It’s like typing a web address that’s so long, it won’t fit in the address bar.
When to use it: Use it when the URL in the request is too long for the server to handle.

415 Unsupported Media Type

What it means: The server can’t understand the format of the data in the request. It’s like trying to play a video file on a music player; it’s the wrong format.
Imagine it like this: It’s like trying to read a document in a language you don’t understand.
When to use it: Use it when the server can’t process the data format sent by the client.

416 Range Not Satisfiable

What it means: The client requested a specific part of a resource, but the server can’t fulfill that request because it’s outside the resource’s size. It’s like trying to read a book starting from page 101 when the book only has 100 pages.
Imagine it like this: It’s like asking for the last 10 minutes of a 5-minute video; it’s not possible.
When to use it: Use it when the client’s request for a specific range can’t be satisfied by the server.

417 Expectation Failed

What it means: The client expected something specific in the response, but the server couldn’t meet that expectation. It’s like ordering a meal at a restaurant and expecting it to be served in 5 seconds, but it takes longer.
Imagine it like this: It’s like expecting a package to be delivered at a certain time, but it arrives late.
When to use it: Use it when the server can’t meet the expectation set by the client’s “Expect” header.

418 I’m a teapot

What it means: A playful and humorous status code. The server refuses the request, stating that it’s a teapot and can’t make coffee. It’s not meant for serious use.
Imagine it like this: It’s like asking your cat to fetch your newspaper; it’s not something it can do.
When to use it: It’s not meant for practical use and should only be used for fun or as an easter egg.

421 Misdirected Request

What it means: The request was directed at a server that can’t respond to it because it’s configured for a different type of request. It’s like asking a bicycle shop for car repair advice.
Imagine it like this: It’s like calling a bakery to ask about computer issues; they can’t help you.
When to use it: Use it when a server receives a request intended for another server or resource.

422 Unprocessable Content (WebDAV)

What it means: The request was well-formed, but it can’t be followed due to semantic errors. It’s like writing a perfectly grammatical sentence that doesn’t make any sense.
Imagine it like this: It’s like trying to solve a puzzle with missing pieces; you can’t complete it.
When to use it: Use it in WebDAV situations when the request can’t be processed due to semantic errors.

423 Locked (WebDAV)

What it means: The resource being accessed is locked by another process or user. It’s like trying to open a document that someone else is editing, and it’s currently locked.
Imagine it like this: It’s like trying to use a tool that someone else is already using; you have to wait your turn.
When to use it: Use it in WebDAV situations when a resource is locked by another process or user.

424 Failed Dependency (WebDAV)

What it means: The request failed because of a failure in a previous request. It’s like trying to build a house, but you can’t because the foundation is faulty.
Imagine it like this: It’s like trying to bake a cake, but you realize you’re out of flour because you used it all in a previous recipe.
When to use it: Use it in WebDAV situations when a request depends on the success of a previous request.

425 Too Early (Experimental)

What it means: The server is unwilling to risk processing a request that might be replayed. It’s meant for preventing security issues related to replayed requests.
Imagine it like this: It’s like a security guard refusing entry to a person who was just there a minute ago, to prevent any mischief.
When to use it: Rarely used, and mostly for security-related concerns to prevent replay attacks.

426 Upgrade Required

What it means: The server won’t fulfill the request using the current protocol but might do so if the client upgrades to a different protocol. It’s like saying, “I can’t talk to you in this language; learn another one, and we can communicate.”
Imagine it like this: It’s like trying to have a conversation with someone who only speaks French, and you need to learn French to continue.
When to use it: Use it when the server requires the client to upgrade to a different protocol for the request to be fulfilled.

428 Precondition Required

What it means: The server requires the request to be conditional, preventing the “lost update” problem, where two updates conflict. It’s like making a purchase with the condition that it’s in stock; if it’s not, you won’t buy it.
Imagine it like this: It’s like telling the seller, “I’ll buy this if it’s available,” to avoid buying something that’s out of stock.
When to use it: Use it when you want to prevent conflicts caused by simultaneous updates.

429 Too Many Requests

What it means: The user sent too many requests in a short amount of time, often used for rate limiting. It’s like telling someone, “You can’t make this many phone calls in a minute; slow down.”
Imagine it like this: It’s like a website saying, “You’ve clicked the ‘refresh’ button too many times in a second; take a break.”
When to use it: Use it when you want to limit the number of requests a client can make within a specified time frame.

431 Request Header Fields Too Large

What it means: The server refuses to process the request because the request’s header fields are too large. It’s like trying to fit a massive book into a small envelope; it won’t fit.
Imagine it like this: It’s like trying to write an address on an envelope, but the address is so long that it won’t fit.
When to use it: Use it when the request’s header fields exceed the server’s allowed size limits.

451 Unavailable For Legal Reasons

What it means: The user requested a resource that can’t be provided for legal reasons, like a censored web page. It’s like asking for a book that’s banned in your country.
Imagine it like this: It’s like trying to access a website that’s blocked in your country due to legal restrictions.
When to use it: Use it when a resource can’t be provided for legal reasons, such as government censorship or legal issues.

500 Internal Server Error

What it means: The server ran into a problem it doesn’t know how to handle. It’s like a chef making a dish and suddenly realizing they forgot the recipe.
Imagine it like this: It’s like calling tech support because your computer crashed, and they don’t know what’s wrong.
When to use it: Use it when something unexpected goes wrong on the server, and it can’t fulfill the request.

501 Not Implemented

What it means: The server doesn’t know how to handle the request method used by the client. It’s like trying to play a game with rules that nobody knows.
Imagine it like this: It’s like attempting to use a remote control that doesn’t have buttons for the functions you want.
When to use it: Use it when the server doesn’t support the HTTP method used in the request, except for GET and HEAD, which all servers must support.

502 Bad Gateway

What it means: The server, acting as a middleman, got an invalid response while trying to process the request. It’s like a mail carrier receiving a damaged package and not knowing what to do with it.
Imagine it like this: It’s like a website trying to load content from another server, but that server is giving errors.
When to use it: Use it when a server acting as a gateway encounters issues while trying to fulfill the request.

503 Service Unavailable

What it means: The server is not ready to handle the request at the moment. It’s like calling a store during their lunch break, and they can’t assist you right now.
Imagine it like this: It’s like trying to access a website, but it’s down for maintenance or overwhelmed with too many visitors.
When to use it: Use it when the server is temporarily unable to handle requests, often due to maintenance or overload. Include a user-friendly message and a “Retry-After” header if possible.

504 Gateway Timeout

What it means: The server, acting as a gateway, couldn’t get a response from another server in time. It’s like ordering food through an app, but the delivery driver is taking forever to pick up your order.
Imagine it like this: It’s like waiting for a webpage to load, but it’s stuck because it’s waiting for data from another server.
When to use it: Use it when a server acting as a gateway times out while waiting for a response from another server.

505 HTTP Version Not Supported

What it means: The server doesn’t support the HTTP version used in the request. It’s like trying to speak a language that the person you’re talking to doesn’t understand.
Imagine it like this: It’s like using an outdated web browser that can’t understand the latest web technology.
When to use it: Use it when the server doesn’t support the HTTP version specified in the request.

506 Variant Also Negotiates

What it means: The server has a configuration error related to content negotiation. It’s not a common status code.
Imagine it like this: It’s like setting up a vending machine, but it’s programmed to negotiate the price with customers, which doesn’t make sense for a vending machine.
When to use it: Rarely used. It indicates an internal server configuration error related to content negotiation.

507 Insufficient Storage (WebDAV)

What it means: The server can’t complete the request because it doesn’t have enough space to store the data required. It’s like trying to save a large file, but your computer’s hard drive is full.
Imagine it like this: It’s like trying to put more books on a full bookshelf; there’s no space.
When to use it: Use it in WebDAV situations when the server lacks storage space to fulfill the request.

508 Loop Detected (WebDAV)

What it means: The server detected an infinite loop while processing the request. It’s like a car’s GPS constantly telling you to make a U-turn, causing you to drive in circles.
Imagine it like this: It’s like a computer program stuck in a never-ending loop, and it can’t break out of it.
When to use it: Use it in WebDAV situations when the server detects an infinite loop in request processing.

510 Not Extended

What it means: Further extensions to the request are needed for the server to fulfill it. It’s like ordering a pizza and being asked, “What toppings do you want?” but you haven’t specified any.
Imagine it like this: It’s like sending an incomplete form that needs more details to be filled in.
When to use it: Use it when the server requires additional information or extensions in the client’s request to complete it.

511 Network Authentication Required

What it means: The client needs to authenticate to gain network access. It’s like needing a security badge to enter a restricted area.
Imagine it like this: It’s like trying to connect to a secure Wi-Fi network that requires a password.
When to use it: Use it when the client needs to provide network authentication to access a resource

Conclusion

In conclusion, we’ve delved into the world of HTTP status codes, gaining a clear understanding of their meanings, practical scenarios, and when to employ them in API development. These status codes serve as vital communication tools between clients and servers, enabling them to convey information about the outcome of requests and the state of resources.

From the informational 1xx codes to the successful 2xx responses, client errors represented by 4xx codes, and server errors indicated by 5xx codes, each status code has a unique purpose and role in the HTTP protocol.

By simplifying these status codes into everyday scenarios, we’ve made it easier to grasp their significance. Whether it’s a “404 Not Found” indicating a missing resource, a “503 Service Unavailable” during maintenance, or a “200 OK” signifying a successful request, these codes play a crucial role in ensuring efficient and meaningful communication in web development.

Understanding when to use these status codes is essential for API developers, as it helps improve the user experience, troubleshoot issues, and maintain the integrity of the web ecosystem. Properly utilizing these codes not only enhances the functionality of APIs but also contributes to the overall reliability and usability of web applications.

In the dynamic landscape of web development, HTTP status codes remain a fundamental aspect, guiding the interactions between clients and servers, and empowering developers to create seamless and user-friendly experiences for internet users worldwide.

Still Curious? Visit my website to know more!

Checkout my Interviews at “Professionals Unplugged”

For more interesting Blogs Visit- Utkarsh Shukla Author