Activity 30: HTTP Status Codes

In RESTful APIs, HTTP status codes are essential for indicating the result of a request. Here’s an overview of the main categories of HTTP status codes and their common uses:

1xx: Informational

These codes let the client know that the request was received and is still being processed:

• 100 Continue: Indicates that the initial part of the request was accepted, and the client can continue sending the rest.

•   HTTP/1.1 100 Continue
  

• 101 Switching Protocols: Confirms a protocol change requested by the client.

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

2xx: Success

These codes mean the request was successfully received and processed:

• 200 OK: The request was successful, and the server is returning the requested data.

GET /users/123 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "Jane Doe",
  "email": "jane@example.com"
}

• 201 Created: A new resource was successfully created, often returned for POST requests.

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

HTTP/1.1 201 Created
Location: /users/124
Content-Type: application/json

{
  "id": 124,
  "name": "John Doe",
  "email": "john@example.com"
}

• 204 No Content: The server processed the request successfully but has no content to return (common for DELETE requests).

DELETE /users/123 HTTP/1.1
Host: api.example.com

HTTP/1.1 204 No Content

3xx: Redirection

Redirection codes indicate the client needs to perform further actions to complete the request:

• 301 Moved Permanently: The resource has a new permanent URL, and future requests should use this new URL.

GET /old-path HTTP/1.1
Host: api.example.com

HTTP/1.1 301 Moved Permanently
Location: /new-path

• 302 Found: The resource temporarily resides at a different URL, and future requests should continue to use the original URL.

HTTP/1.1 302 Found
Location: https://www.example.com/temporary-page

• 307 Temporary Redirect: Similar to 302, but the client should resubmit the request to the new URL.

POST /submit HTTP/1.1
Host: api.example.com

HTTP/1.1 307 Temporary Redirect
Location: https://api.example.com/temp-submit

4xx: Client Errors

Client error codes indicate a problem with the request from the client:

• 400 Bad Request: The server couldn’t understand the request due to invalid syntax.

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane" "email": "jane@example.com" // Missing comma

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid JSON format"
}

• 401 Unauthorized: Authentication is required, but it was not provided or is invalid.

GET /users/123 HTTP/1.1
Host: api.example.com

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Authentication required"
}

• 403 Forbidden: The client is authenticated but doesn’t have permission to access the resource.

GET /admin HTTP/1.1
Host: api.example.com

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "You do not have permission to access this resource"
}

• 404 Not Found: The server can’t find the requested resource.

GET /users/999 HTTP/1.1
Host: api.example.com

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "User not found"
}

• 429 Too Many Requests: The client has sent too many requests in a short period, triggering rate limiting.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": "Too many requests",
  "message": "You have exceeded the rate limit. Please wait 60 seconds before trying again."
}

5xx: Server Errors

These codes mean the server encountered an error while processing the request:

• 500 Internal Server Error: A general error when the server encounters an unexpected issue.

GET /users HTTP/1.1
Host: api.example.com

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "An unexpected error occurred. Please try again later."
}

• 502 Bad Gateway: A server acting as a gateway received an invalid response from an upstream server.

HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{
  "error": "Bad Gateway",
  "message": "The server received an invalid response from the upstream server."
}

• 503 Service Unavailable: The server is temporarily unable to handle the request, often due to maintenance or overload.

GET /users HTTP/1.1
Host: api.example.com

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "error": "Service is temporarily unavailable. Please try again later."
}

• 504 Gateway Timeout: A server acting as a gateway did not receive a timely response from an upstream server.

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json

{
  "error": "Gateway Timeout",
  "message": "The server did not receive a timely response from the upstream server."
}

Each status code provides specific information to clients and is fundamental in REST API design, where they help manage client-server interactions effectively. Understanding and using the appropriate status codes will enhance the client experience by providing clear feedback on the request status