How to Read and Debug HTTP Status Codes

HTTP status codes are the server's way of communicating exactly what happened with your request. A three-digit number tells you whether it succeeded, redirected, failed on your end, or failed on the server's end. Once you know the pattern, they become your first and fastest debugging tool when working with APIs and web applications.

The DevToolShack HTTP Status Codes reference has every code with its meaning and common use cases — a quick lookup when you encounter something unfamiliar.

The Five Classes

The first digit of every status code tells you which category it falls into — this alone gets you 80% of the way to diagnosing a problem:

Class	Range	Meaning
1xx	100–199	Informational — request received, processing continues
2xx	200–299	Success — request was received, understood, and accepted
3xx	300–399	Redirection — further action needed to complete the request
4xx	400–499	Client error — the request has a problem on your end
5xx	500–599	Server error — the server failed to fulfil a valid request

Quick mental model: 4xx means you did something wrong (bad request, not authenticated, not found). 5xx means the server did something wrong. This distinction immediately tells you where to look when debugging.

The Codes You'll See Every Day

2xx — Success

Code	Name	When You'll See It
`200`	OK	Standard successful response for GET, POST, PUT requests
`201`	Created	Resource was created — the correct response for a successful POST that creates a new record
`204`	No Content	Success but no body to return — correct for DELETE requests and some PUTs
`206`	Partial Content	Range request fulfilled — used for streaming video and resumable downloads

3xx — Redirects

Code	Name	When You'll See It
`301`	Moved Permanently	URL has permanently moved — browsers and search engines update their records
`302`	Found	Temporary redirect — don't update bookmarks or SEO signals
`304`	Not Modified	Cached version is still valid — browser uses its local copy
`307`	Temporary Redirect	Like 302 but guarantees the HTTP method is preserved (POST stays POST)
`308`	Permanent Redirect	Like 301 but preserves HTTP method — use this instead of 301 for API endpoints

4xx — Client Errors

Code	Name	Typical Cause
`400`	Bad Request	Malformed request syntax, invalid parameters, missing required fields
`401`	Unauthorized	Authentication required or token invalid/expired
`403`	Forbidden	Authenticated but not allowed — wrong permissions, not just not logged in
`404`	Not Found	Resource doesn't exist at this URL
`405`	Method Not Allowed	Wrong HTTP method — POST to a GET-only endpoint
`409`	Conflict	Resource state conflict — duplicate record, version mismatch
`410`	Gone	Resource existed but has been permanently deleted
`422`	Unprocessable Entity	Request is well-formed but fails validation — used heavily in REST APIs
`429`	Too Many Requests	Rate limit hit — check the `Retry-After` header

5xx — Server Errors

Code	Name	Typical Cause
`500`	Internal Server Error	Generic server crash — check server logs for the real error
`502`	Bad Gateway	Proxy/load balancer got an invalid response from the upstream server
`503`	Service Unavailable	Server overloaded or down for maintenance
`504`	Gateway Timeout	Upstream server didn't respond in time — often a slow database query

The 401 vs 403 Confusion

These two are frequently mixed up, even by experienced developers:

401 Unauthorized — means "you haven't proven who you are yet." Send credentials. Despite the name, it's really an authentication error.
403 Forbidden — means "I know who you are, but you're not allowed to do this." An authorization error. Sending credentials again won't help.

Using the cURL Generator to Test Status Codes

When debugging API issues, testing the raw request with cURL eliminates browser, CORS, and JavaScript variables. The cURL Generator builds the command for you — paste in your endpoint, headers, and body, and get a cURL command ready to run:

# Test an API endpoint and show response headers
curl -i -X GET https://api.example.com/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# The -i flag shows response headers including the status code
# HTTP/2 200
# content-type: application/json

Bookmark the reference: The HTTP Status Codes tool is a searchable reference with every code, its RFC definition, and common use cases. Much faster than Googling "what is 422" mid-debug session.

Choosing the Right Code for Your API

When building APIs, using the right status code matters — it's part of your contract with API consumers:

Return 201 (not 200) when a resource is created
Return 204 (not 200) for successful deletes with no body
Return 422 for validation failures, not 400 (400 is for malformed syntax)
Return 409 for conflicts like duplicate records, not 400
Always include a Retry-After header with 429 responses
Never return 200 with an error in the body — that breaks every HTTP client

How to Read and Debug HTTP Status Codes

The Five Classes

The Codes You'll See Every Day

2xx — Success

3xx — Redirects

4xx — Client Errors

5xx — Server Errors

The 401 vs 403 Confusion

Using the cURL Generator to Test Status Codes

Choosing the Right Code for Your API

Related Articles