What are HTTP status codes?

HTTP status codes are three-digit numbers returned by servers to indicate the result of a HTTP request. They tell the client whether the request succeeded, failed, or needs additional action. Codes are grouped into five categories: 1xx (informational), 2xx (success), 3xx (redirect), 4xx (client error), 5xx (server error).

What is the most common HTTP error code?

The most common HTTP error codes are 404 Not Found (page or resource doesn't exist), 500 Internal Server Error (generic server failure), and 403 Forbidden (access denied). These three account for most error responses users encounter.

When should I use 404 vs 410 status code?

Use 404 Not Found when a resource doesn't exist or you don't want to reveal whether it exists. Use 410 Gone when a resource previously existed but has been permanently removed. 410 helps search engines remove the URL from their index faster.

What HTTP status code should I return for successful API requests?

For successful API requests: use 200 OK for general success, 201 Created when a new resource is created, 204 No Content for successful deletion or updates with no response body. Always return the appropriate code, not just 200 for everything.

Back to Tutorials

HTTP Status Codes Guide: Complete Reference for API Developers

Understanding HTTP status codes is essential for debugging APIs, handling errors, and building robust web applications. This guide covers all status code categories with practical examples.

Quick Reference

1xx

Informational

2xx

Success

3xx

Redirect

4xx

Client Error

5xx

Server Error

1xx Informational

Informational codes indicate the server received the request and is continuing to process it. These are rarely seen in typical web applications.

Code	Name	Description
100	Continue	Server received request headers, client should continue sending body
101	Switching Protocols	Server agrees to switch protocol (e.g., HTTP to WebSocket)
102	Processing	Server is processing the request but no response is available yet

2xx Success

Success codes confirm the server received, understood, and accepted the request. These are the most common responses for working applications.

Code	Name	Description
200	OK	Standard success response. Request succeeded.
201	Created	New resource created successfully. Common for POST requests.
202	Accepted	Request accepted for processing, but not completed yet.
204	No Content	Success with no response body. Common for DELETE requests.
206	Partial Content	Server delivered partial content (for range requests).

Best Practice: Choose the Right Success Code

• 200 OK: General success, GET requests
• 201 Created: POST creating new resources
• 204 No Content: DELETE, PUT updates with no body
• Don't return 200 for everything - use appropriate codes

3xx Redirect

Redirect codes indicate the client needs to take additional action to complete the request, typically by following a new URL.

Code	Name	Description
301	Moved Permanently	Resource moved to new URL permanently. Update your links.
302	Found	Resource temporarily at different URL. Use original URL for future requests.
304	Not Modified	Resource unchanged since last request. Use cached version.
307	Temporary Redirect	Temporary redirect, preserve request method.
308	Permanent Redirect	Permanent redirect, preserve request method.

301 vs 302: Permanent vs Temporary

• 301 Moved Permanently: Use when URL changes forever. SEO value transfers to new URL.
• 302 Found: Temporary redirect. SEO value stays at original URL.
• 304 Not Modified: Saves bandwidth - client uses cached version.

4xx Client Error

Client error codes indicate the request contained bad syntax or could not be fulfilled. The client needs to fix the request before retrying.

Code	Name	Description
400	Bad Request	Malformed request syntax. Check your request format.
401	Unauthorized	Authentication required. Log in or provide credentials.
403	Forbidden	Server understands request but refuses to authorize it.
404	Not Found	Resource doesn't exist at specified URL.
405	Method Not Allowed	HTTP method not supported for this resource.
408	Request Timeout	Server timed out waiting for request.
409	Conflict	Request conflicts with current state of resource.
410	Gone	Resource no longer available and won't return.
413	Payload Too Large	Request body exceeds server limits.
414	URI Too Long	Requested URL is too long.
415	Unsupported Media Type	Media format not supported by server.
422	Unprocessable Entity	Request well-formed but semantically incorrect.
429	Too Many Requests	Rate limit exceeded. Slow down your requests.

Most Common Client Errors

• 400 Bad Request: Malformed JSON, missing parameters
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Valid auth but insufficient permissions
• 404 Not Found: Wrong URL or resource doesn't exist
• 429 Too Many Requests: Rate limiting - slow down your calls

5xx Server Error

Server error codes indicate the server failed to fulfill a valid request. These are often temporary issues or server-side bugs.

Code	Name	Description
500	Internal Server Error	Generic server error. Something went wrong on the server.
501	Not Implemented	Server doesn't support the requested functionality.
502	Bad Gateway	Server received invalid response from upstream server.
503	Service Unavailable	Server temporarily unavailable (overloaded or maintenance).
504	Gateway Timeout	Server didn't receive timely response from upstream.

Handling Server Errors in Your App

• 500: Generic error - check server logs for details
• 502/503/504: Often temporary - implement retry logic
• Show user-friendly messages, not raw error codes
• Log errors with context for debugging

Best Practices for API Status Codes

1. Use Appropriate Codes

Don't return 200 for everything. Use 201 for created resources, 204 for deletions, 400 for validation errors, 404 for missing resources. This makes debugging easier.

2. Include Error Details

For error responses, include a JSON body with error type, message, and field-level details. This helps clients fix issues quickly.

{
  "error": "validation_failed",
  "message": "Invalid input data",
  "details": {
    "email": "Invalid email format",
    "age": "Must be a positive number"
  }
}

3. Distinguish 401 vs 403

401 Unauthorized: User not logged in or token invalid/expired.403 Forbidden: User logged in but lacks permission for this action. This distinction helps implement proper auth flows.

4. Handle Rate Limiting Properly

Return 429 Too Many Requests with headers indicating retry-after time. Implement exponential backoff on the client side.

Debugging HTTP Errors

Check Request Format

400 errors often mean malformed JSON or wrong parameters. Validate your request body with our JSON Validator.

Read Error Response

Don't ignore the response body. Most APIs include error details that tell you exactly what went wrong.

Server Logs

500 errors require server-side investigation. Check application logs, database connections, and server resources.

Follow Redirects

3xx codes often indicate URL changes. Check the Location header and update your API endpoints accordingly.