HTTP status codes, explained
Status codes are defined in RFC 9110, HTTP Semantics, with a few in separate RFCs such as 429 Too Many Requests (RFC 6585). The first digit gives the class, so clients can handle unfamiliar codes by their class.
- 1xx informational:
100 Continue,101 Switching Protocols. - 2xx success:
200 OK,201 Created,202 Accepted,204 No Content. - 3xx redirection:
301 Moved Permanently,304 Not Modified,307and308redirects that keep the method. - 4xx client errors:
400 Bad Request,401 Unauthorized(not authenticated),403 Forbidden(authenticated but not allowed),404 Not Found,409 Conflict,410 Gone,422 Unprocessable Content,429 Too Many Requests. - 5xx server errors:
500 Internal Server Error,502 Bad Gateway,503 Service Unavailable,504 Gateway Timeout.
Clients branch on status codes for retries, error messages and control flow. Retrying on 429 or 503 (honouring Retry-After) is safe; retrying on 400 is not. That makes the status code part of the contract: switching a validation error from 400 to 422, or returning 200 where a client expects 201, is a breaking change even though no field changed.
Related terms
- REST API: A REST API is an HTTP API organised around resources identified by URLs and manipulated with standard methods such as GET, POST, PUT, PATCH and DELETE.
- Rate limiting: Rate limiting caps how many requests a client can make to an API in a given time window, protecting the service from overload and abuse.
- Breaking change: A breaking change is a change to an API that causes a correctly written client, which worked before, to fail or behave differently without modifying its code.
- API endpoint: An API endpoint is a specific address, usually a URL path combined with an HTTP method, where a client sends requests to perform one operation on an API.