Understanding HTTP Status Codes

Introduction

The status code of a response is a three-digit integer code that describes the result of the request and the semantics of the response, including whether the request was successful and what content is enclosed (if any). All valid status codes are within the range of 100 to 599, inclusive.

The first digit defines the class of response; the last two digits don't have any categorization role.

There are five classes:

1xx – Informational: request received, still processing

2xx – Success: request was received, understood, and accepted

3xx – Redirection: further action needed to complete the request

4xx – Client Error: the request has bad syntax or can't be fulfilled

5xx – Server Error: the server failed to fulfill a valid request

— RFC 9110, Section 15: Status Codes

Informational Responses

Code	Name	Meaning
100	Continue	The server has received the initial part of the request and the client should continue sending the request body.
101	Switching Protocols	The server is switching to a different protocol as requested by the client.
102	Processing	The server has received and is processing the request, but no response is available yet.
103	Early Hints	The server sends preliminary response headers before the final response, allowing the client to begin loading resources early.
104	Upload Resumption Supported	Indicates support for resumable uploads. This status code is currently an experimental extension and not widely implemented.
105	Unused	This status code is reserved and has no defined HTTP semantics.
106	Unused	This status code is reserved and has no defined HTTP semantics.
107	Unused	This status code is reserved and has no defined HTTP semantics.
108	Unused	This status code is reserved and has no defined HTTP semantics.
109	Unused	This status code is reserved and has no defined HTTP semantics.
Rarely seen in typical REST API work.

Successful Responses

Code	Name	Meaning
200	OK	The request succeeded. The response contains the requested result or representation.
201	Created	The request succeeded and resulted in the creation of a new resource.
202	Accepted	The request has been accepted for processing, but the processing has not been completed yet.
203	Non-Authoritative Information	The request succeeded, but the returned metadata may come from a source different from the origin server.
204	No Content	The request succeeded, but there is no additional content to send in the response body.
205	Reset Content	The request succeeded and the client should reset the document view or input state.
206	Partial Content	The server is delivering only part of the requested resource, usually because of a range request.
207	Multi-Status	The response contains multiple status values for different operations or resources.
208	Already Reported	The members of a WebDAV collection have already been reported in a previous response.
226	IM Used	The server successfully fulfilled a request using instance manipulations.
Most commonly used in REST APIs: 200, 201, 202, and 204.

Diagram showing HTTP request and response cycle between client and server — Basic HTTP request/response cycle: a client sends a request to a server, and the server returns a response with a status code.

When should I use 201 vs 200?

Use 201 Created when the request creates a new resource on the server.

Example:

                            
           POST /users
         Response:
                    HTTP/1.1 201 Created

{
                "id": 123,
                    "name": "John"
}

Use 200 OK when the request succeeds but does not create a new resource.

Examples:

GET /users/123 → returns an existing user
PUT /users/123 → updates an existing user
POST /search → performs a search operation and returns results

Rule of thumb:
New resource created → 201 Created
Successful operation without creating a resource → 200 OK

Redirection Messages

300 Multiple Choices: The request has more than one possible response. The user agent may choose one of the available representations or follow further instructions.
301 Moved Permanently: The requested resource has been permanently moved to a new URI. Clients should update bookmarks and search engines should update their indexes.
302 Found: The requested resource is temporarily available at a different URI. The client should continue using the original URI for future requests.
303 See Other: The server redirects the client to another URI where it can retrieve the result, usually using the GET method.
304 Not Modified: The resource has not changed since the version specified by the request headers. The client can use its cached copy instead of downloading it again.
305 Use Proxy: The requested resource must be accessed through the proxy specified in the response. This status code is deprecated and should not be used.
306 (Unused): This status code was previously used but is no longer assigned. It is reserved for future use.
307 Temporary Redirect: The resource is temporarily available at another URI. Unlike 302, the client must preserve the original HTTP method when following the redirect.
308 Permanent Redirect: The resource has been permanently moved to another URI. Unlike 301, the client must preserve the original HTTP method when following the redirect.
310 Not Further Extended: An unofficial extension status code used by some systems to indicate that further extensions are required. It is not part of the standard HTTP status code registry.

Client Error Responses

Code	Name	Meaning
400	Bad Request	The server cannot process the request because the client sent invalid syntax, invalid data, or malformed request parameters.
401	Unauthorized	The request requires valid authentication credentials. The client must authenticate itself before accessing the resource.
403	Forbidden	The server understood the request but refuses to authorize it. Authentication may be valid but the client does not have permission.
404	Not Found	The server cannot find the requested resource or does not want to reveal that it exists.
409	Conflict	The request conflicts with the current state of the target resource, such as creating a resource that already exists.
422	Unprocessable Content	The server understands the request format, but the provided data is semantically invalid and cannot be processed.
429	Too Many Requests	The client has sent too many requests in a given amount of time. Commonly used for rate limiting.
Common REST API client errors: 400, 401, 403, 404, 409, 422, and 429.


                        HTTP/1.1 404 Not Found
                                Content-Type: application/json
                         Cache-Control: no-cache
                        
  {
                                "error": "User not found",
                   "status": 404
  }

To inspect HTTP requests and responses, open the browser developer tools: press F12 and go to the Network tab.

Example API error logged in the browser console:

GET https://api.example.com/users/999 404 (Not Found)

Common REST API meanings:

400 Bad Request → Invalid input format or missing required fields
401 Unauthorized → Missing or invalid authentication token
403 Forbidden → User authenticated but lacks permission
404 Not Found → Resource does not exist
409 Conflict → Resource state conflict (duplicate data, version conflict)
422 Unprocessable Content → Validation errors
429 Too Many Requests → Rate limit exceeded

Server Error Responses

Code	Name	Meaning
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.
502	Bad Gateway	The server, acting as a gateway or proxy, received an invalid response from an upstream server.
503	Service Unavailable	The server is currently unable to handle the request, usually because of temporary overload or scheduled maintenance.
504	Gateway Timeout	The server acting as a gateway or proxy did not receive a timely response from an upstream server.
Server errors usually indicate problems on the server side, not with the client's request.

Production War Story: The Unexpected 503

During a production deployment, an application started returning 503 Service Unavailable errors. The application itself was running, but the database connection pool was exhausted because a new release accidentally created too many long-running queries.

Monitoring alerts helped identify that the service was healthy at the process level but unable to serve requests. After rolling back the release and fixing the query issue, the service recovered.

The lesson: a server can be "up" while still being unable to successfully handle user requests.

Common REST/API meanings:

500 Internal Server Error → Unexpected application failure
502 Bad Gateway → Reverse proxy received an invalid upstream response
503 Service Unavailable → Service temporarily unavailable or overloaded
504 Gateway Timeout → Upstream service did not respond in time

Glossary

Idempotent: An operation that produces the same result when performed multiple times as when performed once. For example, sending the same PUT request multiple times should leave the resource in the same final state.
Safe method: An HTTP method that does not modify the state of the server. Safe methods are intended only for retrieving information. Examples include GET and HEAD.
Payload: The data sent inside the body of an HTTP request or response. In REST APIs, payloads are commonly formatted as JSON and contain the resource data being created, updated, or returned.
Header: Metadata sent with an HTTP request or response. Headers provide additional information such as content type, authentication credentials, caching rules, and client/server capabilities.
Status line: The first line of an HTTP response that contains the HTTP version, status code, and reason phrase. Example: HTTP/1.1 200 OK

Footnotes

RFC 9110 defines status codes as three-digit integers indicating the result of an attempt to understand and satisfy an HTTP request. ↩
Safe HTTP methods are methods intended not to change the state of the target resource. GET and HEAD are examples of safe methods. ↩

Quick Quiz: What does this code mean?

Quiz What does HTTP status code 418 I'm a Teapot mean?