HTTP Status Codes

An HTTP status code is a three-digit number a server returns in every response to signal what happened to the request. The first digit defines the class; the remaining two refine it. Clients and intermediaries (caches, proxies, load balancers) rely on these codes to react without parsing the body, which is why a REST API should pick the most specific code that fits.

The five classes

Class	Range	Meaning
`1xx`	Informational	Request received, processing continues
`2xx`	Success	The request was received, understood, and accepted
`3xx`	Redirection	Further action is needed to complete the request
`4xx`	Client error	The request is malformed or not allowed
`5xx`	Server error	The server failed to fulfill a valid request

Common codes

Code	Name	When to use
`200`	OK	Successful `GET`, `PUT`, or `PATCH` returning a body
`201`	Created	A `POST` created a resource; return its `Location`
`202`	Accepted	Work was queued for async processing
`204`	No Content	Success with no body (often `DELETE` or `PUT`)
`301`	Moved Permanently	Resource has a new canonical URL
`304`	Not Modified	Cached representation is still valid
`400`	Bad Request	Malformed syntax or invalid parameters
`401`	Unauthorized	Authentication is missing or invalid
`403`	Forbidden	Authenticated but not allowed
`404`	Not Found	No resource at this URL
`409`	Conflict	Request conflicts with current state
`422`	Unprocessable Entity	Syntactically valid but semantically wrong
`429`	Too Many Requests	Rate limit exceeded; honor `Retry-After`
`500`	Internal Server Error	Unexpected server fault
`502`	Bad Gateway	Upstream returned an invalid response
`503`	Service Unavailable	Temporarily overloaded or down

Choosing the right code

Prefer the most specific code over a generic one (422 over a bare 400 when the payload parses but fails validation).
Reserve 5xx for server faults. A rejected-but-valid request is a 4xx, not a 500.
Pair codes with headers clients act on: Location on 201, Retry-After on 429/503, WWW-Authenticate on 401, ETag/Last-Modified for 304.
Keep codes consistent across endpoints so retries and idempotent handling behave predictably; see webhook reliability patterns for retry-driven examples.

POST /orders HTTP/1.1
Content-Type: application/json

{ "item": "sku-123", "qty": 2 }

HTTP/1.1 201 Created
Location: /orders/43

The five classes

Common codes

Choosing the right code

See also

On Wikipedia