HTTP Response Status Codes

• used to indicate the status / result of the HTTP request made
• these can be classified into
  1. Informational responses [1xx]
  2. Successful responses [2xx]
  3. Redirection messages [3xx]
  4. Client error responses [4xx]
  5. Server error responses [5xx]

Informational Responses (1xx)

• Informational responses (1xx) indicate that the request has been received and the process is continuing.

• They are mainly used for preliminary communication before the final response is sent.

Example: Large File Upload

When a client wants to send a very large file:

1. The client first sends the request headers only, including Content-Length, Content-Type, Expect: 100-continue

2. The server checks the request headers and performs processes like Authentication, Authorization and performs validations ensuring File size limits, Content type validity

3. At the enn, server responds with:

   • 100 Continue → Client can now send the file body
   • OR a final error like 401 Unauthorized, 403 Forbidden, 413 Payload Too Large
   • This prevents the client from uploading a huge file if the request will be rejected anyway.

Use-cases and Status Codes

Status Code	Name	Purpose
100	Continue	Generic error: Client should continue sending request body
101	Switching Protocols	Server agrees to protocol upgrade
102	Processing	Request received and still being processed
103	Early Hints	Allows browser to preload resources early

• In most backend frameworks these request expecting response 1xx are temporary and handle them automatically. They are rarely used directly in REST API logic.

Successful responses [2xx]

• Successful responses (2xx) indicate that request is received, understood and processed successfully

• These response can be added to most of the http request types and is used

Use-cases

Status Code	Name	Purpose
200	OK	Generic error: Standard success response; data returned successfully (GET, PUT, PATCH).
201	Created	Resource successfully created (POST).
202	Accepted	Request accepted but processing happens asynchronously.
203	Non-Authoritative	Response from proxy/modification, not directly from origin server.
204	No Content	Success, but no response body (DELETE, some updates).
205	Reset Content	Request succeeded, client should reset the view/form.
206	Partial Content	Partial response for range requests (download/resume).

Redirection messages [3xx]

• Redirection messages [3xx] status codes indicate that the requested resource is available but at a different path / URL / location.

• In these cases, to complete and fulfill the request, the client should take extra steps like:

  1. make another request to new location
  2. forwards requests via proxy through proxy handling
  3. caching (using data already given in previous request)
  4. switching method

Use-cases and Status Codes

Status Code	Name	Purpose
300	Multiple Choices	Generic error: Multiple options for the resource; client may choose one.
301	Moved Permanently	Resource permanently moved to a new URL; update bookmarks/links.
302	Found / Temporary Redirect	Resource temporarily located at a different URL; original URL still valid.
303	See Other	Redirect to another URL using GET (commonly after POST).
304	Not Modified	Resource not changed; client can use cached version.
305	Use Proxy	Resource must be accessed through a proxy (rarely used).
307	Temporary Redirect	Like 302, but HTTP method must not change (POST remains POST).
308	Permanent Redirect	Like 301, but HTTP method must not change (method preserved).

Client error responses [4xx]

• Client error responses [4xx] indicate that request made is incorrect and cannot be process

• These can be due to

  1. malformed request syntax i.e header or body errors
  2. using wrong http methods
  3. unauthorized access
  4. validation errors

• In these cases server will not process the request but client can retry with corrected request next time.

Use-cases and Status Codes

Status Code	Name	Purpose
400	Bad Request	Generic errorMalformed request syntax or invalid request.
401	Unauthorized	Client must authenticate to access the resource.
402	Payment Required	Reserved for digital payment; rarely used.
403	Forbidden	Client is authenticated but not authorized to access the resource.
404	Not Found	Resource does not exist; endpoint valid but resource missing.
405	Method Not Allowed	HTTP method not supported by the resource.
406	Not Acceptable	No content matching client’s requested criteria.
407	Proxy Authentication Required	Client must authenticate with proxy.
408	Request Timeout	Server timed out waiting for the client to send the request.
409	Conflict	Request conflicts with the current state of the server.
410	Gone	Resource permanently deleted; no forwarding address.
411	Length Required	Request missing Content-Length header.
412	Precondition Failed	Conditional request headers not met by server.
413	Content Too Large	Request body exceeds server-defined size limits.
414	URI Too Long	Requested URI is longer than server is willing to process.
415	Unsupported Media Type	Server does not support the format of the request body.
416	Range Not Satisfiable	Requested range cannot be fulfilled by the server.
417	Expectation Failed	Server cannot meet the Expect request header.
418	I’m a teapot	April Fools / humorous response; server refuses to brew coffee.
421	Misdirected Request	Request sent to a server unable to produce a valid response.
422	Unprocessable Content	Well-formed request but semantic errors prevent processing.
423	Locked	Resource is currently locked (WebDAV).
424	Failed Dependency	Request failed because a previous request failed.
425	Too Early	Server refuses to process a request that may be replayed.
426	Upgrade Required	Client must switch protocols (Upgrade header sent).
428	Precondition Required	Request must be conditional to prevent lost updates.
429	Too Many Requests	Rate limiting; client sent too many requests in a short time.
431	Request Header Fields Too Large	Header fields too large; client must reduce size.
451	Unavailable For Legal Reasons	Resource unavailable due to legal reasons (e.g., censorship).

Server error responses [5xx]

• Server error responses indicate that the server failed to fulfill a valid request due to an issue on the server side.

1. Bugs and errors in backend code.
2. Backend server crashed, overloaded, or temporarily unavailable.
3. Services used by the backend are unavailable.
4. Unsupported functionality, such as incorrect HTTP protocol version.
5. Resource limitations, like disk full, memory exhausted, storage limits exceeded, infinite loops, or resource deadlocks.

• These errors usually mean the client did nothing wrong, and retrying may succeed once the server issue is resolved. They are commonly used in backend APIs when services crash, are unavailable, or encounter unexpected conditions.

Use-cases and Status Codes

Status Code	Name	Purpose
500	Internal Server Error	Generic error: server encountered a situation it does not know how to handle.
501	Not Implemented	Request method not supported by the server (except GET/HEAD).
502	Bad Gateway	Server acting as a gateway received an invalid response from upstream.
503	Service Unavailable	Server temporarily unavailable (maintenance or overload); Retry-After header recommended.
504	Gateway Timeout	Server acting as a gateway did not get a response in time from upstream.
505	HTTP Version Not Supported	HTTP version used in the request is not supported by the server.
506	Variant Also Negotiates	Internal configuration error; circular content negotiation detected.
507	Insufficient Storage	Server cannot store the representation needed to complete the request.
508	Loop Detected	Infinite loop detected while processing the request (WebDAV).
510	Not Extended	HTTP extension required by client is not supported.
511	Network Authentication Required	Client must authenticate to gain network access.

Production-Grade API Response Guidelines

In production, always ensure your APIs:

1. Return specific and relevant HTTP status codes that accurately reflect the result or error.
2. Include a JSON response body describing success or error with meaningful information so clients can handle responses programmatically.
3. Never expose sensitive data including stack traces, internal server paths, database queries, or secrets in responses but only send safe messages to clients.