HTTP - Status Codes

HTTP Status Codes Reference

http api reference

---

Quick Reference by Category

1xx: Informational

Code	Name	Description
100	Continue	Client can continue sending the rest of the request
101	Switching Protocols	Server agrees to switch protocols (e.g., WebSocket upgrade)

---

2xx: Success

Code	Name	Description
200	OK	Request succeeded
201	Created	New resource created successfully
202	Accepted	Request accepted for processing (async)
204	No Content	Success, but no content in response body

---

3xx: Redirection

Code	Name	Description
301	Moved Permanently	Resource permanently moved to new URL
302	Found	Resource temporarily moved (commonly misused)
303	See Other	Redirect to different URI using GET
304	Not Modified	Resource unchanged; use cached version
307	Temporary Redirect	Temporary redirect, preserve method
308	Permanent Redirect	Permanent redirect, preserve method

---

4xx: Client Error

Code	Name	Description
400	Bad Request	Malformed syntax or invalid request
401	Unauthorized	Authentication required or failed
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource doesn’t exist
405	Method Not Allowed	HTTP method not supported for this resource
409	Conflict	Request conflicts with current state
410	Gone	Resource permanently deleted
422	Unprocessable Entity	Validation error (WebDAV, common in APIs)
429	Too Many Requests	Rate limit exceeded

---

5xx: Server Error

Code	Name	Description
500	Internal Server Error	Unexpected server-side error
501	Not Implemented	Server doesn’t support this functionality
502	Bad Gateway	Invalid response from upstream server
503	Service Unavailable	Server overloaded or in maintenance
504	Gateway Timeout	Upstream server didn’t respond in time

---

API Design: When to Use Which

Creating Resources (POST)

Scenario	Status Code
Resource created successfully	201 Created (with Location header)
Creation queued/async processing	202 Accepted
Validation failed	400 Bad Request or 422 Unprocessable Entity
Duplicate resource	409 Conflict

Reading Resources (GET)

Scenario	Status Code
Resource found	200 OK
Resource not found	404 Not Found
Resource deleted	410 Gone (if you want to indicate it existed)
Not modified (with ETag/If-None-Match)	304 Not Modified

Updating Resources (PUT/PATCH)

Scenario	Status Code
Update successful, return resource	200 OK
Update successful, no content	204 No Content
Resource doesn’t exist	404 Not Found
Concurrent modification conflict	409 Conflict
Validation failed	400 Bad Request or 422 Unprocessable Entity

Deleting Resources (DELETE)

Scenario	Status Code
Deleted successfully	204 No Content
Resource not found	404 Not Found
Cannot delete (dependencies)	409 Conflict

Authentication/Authorization

Scenario	Status Code
Not logged in / invalid token	401 Unauthorized
Logged in but not permitted	403 Forbidden
API key missing	401 Unauthorized
Rate limit exceeded	429 Too Many Requests

---

Troubleshooting Guide

400 Bad Request

• Check JSON syntax (missing quotes, trailing commas)
• Verify Content-Type header matches body format
• Check required fields are present
• Validate data types (string vs number)

401 Unauthorized

• Token expired? Refresh or re-authenticate
• Missing Authorization header
• Wrong auth scheme (Bearer vs Basic)
• API key in wrong location (header vs query param)

403 Forbidden

• User lacks required permissions/roles
• Resource-level access denied
• IP not whitelisted
• CORS preflight failed (check origin)

404 Not Found

• Check URL path spelling
• Check if ID/slug exists
• API version in URL correct?
• Trailing slash issues

500 Internal Server Error

• Check server logs for stack trace
• Recent deployment issues
• Database connection problems
• Null pointer / unhandled exception

502 Bad Gateway

• Upstream service down
• Load balancer can’t reach backend
• Backend crashed or not responding
• Check health endpoints

503 Service Unavailable

• Service overloaded
• Planned maintenance (check Retry-After header)
• Circuit breaker tripped
• Resource exhaustion (memory, connections)

504 Gateway Timeout

• Upstream service slow
• Database query timeout
• Long-running operation (use async)
• Increase timeout or optimize

---

Common Headers with Status Codes

Header	Used With	Purpose
Location	201, 3xx	URL of created/redirected resource
Retry-After	429, 503	When to retry (seconds or date)
WWW-Authenticate	401	Auth scheme required
ETag	200, 304	Resource version for caching
X-RateLimit-*	429	Rate limit details

---

Full Reference Table

Category	Code	Name	Description
1xx Informational	100	Continue	Client should continue with request
1xx Informational	101	Switching Protocols	Server switching protocols
1xx Informational	102	Processing (WebDAV)	Server processing, no response yet
2xx Success	200	OK	Request succeeded
2xx Success	201	Created	New resource created
2xx Success	202	Accepted	Accepted for async processing
2xx Success	204	No Content	Success with no body
3xx Redirection	301	Moved Permanently	New permanent URI
3xx Redirection	302	Found	Temporary redirect
3xx Redirection	303	See Other	Redirect with GET
3xx Redirection	304	Not Modified	Use cached version
3xx Redirection	307	Temporary Redirect	Temp redirect, keep method
4xx Client Error	400	Bad Request	Malformed request
4xx Client Error	401	Unauthorized	Auth required/failed
4xx Client Error	403	Forbidden	Access denied
4xx Client Error	404	Not Found	Resource not found
4xx Client Error	405	Method Not Allowed	Method not supported
4xx Client Error	409	Conflict	State conflict
4xx Client Error	410	Gone	Permanently removed
4xx Client Error	422	Unprocessable Entity	Validation error
4xx Client Error	429	Too Many Requests	Rate limited
5xx Server Error	500	Internal Server Error	Unexpected server error
5xx Server Error	501	Not Implemented	Feature not supported
5xx Server Error	502	Bad Gateway	Invalid upstream response
5xx Server Error	503	Service Unavailable	Server overloaded/maintenance
5xx Server Error	504	Gateway Timeout	Upstream timeout