Understanding REST API Status Codes (1xx–5xx) with Simple Examples

Quick Summary

Whenever you call a REST API, the very first clue about what happened is the HTTP status code. Learning to “read” these numbers makes debugging and API design much faster.

All status codes are three digits and are grouped into five families: 1xx (informational), 2xx (success), 3xx (redirection), 4xx (client error) and 5xx (server error).

You do not need to memorize every code. Instead, focus on understanding what each family means and a few representative codes such as 200, 201, 204, 301, 400, 401, 404, 409, 500, and 503.

In this post we will walk through each status family, learn common codes with plain-English explanations, and practice how to use them correctly in real REST APIs.

1. What are HTTP and REST API status codes?
2. The five status code families (1xx–5xx)
3. Common status codes you should know
4. Practical code examples
5. Best practices when designing APIs
6. Step-by-step learning plan

Key Takeaways

Every status code starts with 1, 2, 3, 4 or 5, and that first digit already tells you if things went well (2xx) or if there was an error (4xx or 5xx).
2xx = success: use 200 for a normal successful response, 201 for creation, and 204 when there is no response body.
3xx = redirection: these codes indicate that the client should request a different URL (for example after a permanent redirect).
4xx = client error: something is wrong with the request (bad data, missing authentication, invalid URL, etc.). The client is expected to fix it.
5xx = server error: the server failed to process a valid request. The problem is on the server side, not the client side.
Consistent status codes improve API UX: clear, predictable codes plus helpful error messages make your API easier to integrate and maintain.

Detailed Explanation

1. What are HTTP and REST API status codes?

HTTP is the protocol that your browser, mobile app, or backend service uses to talk to web servers. Every time a client sends an HTTP request, the server answers with an HTTP response that includes a status line. In that status line there is a three-digit status code such as 200 or 404.

In REST APIs we reuse the same HTTP status codes. Instead of inventing our own “error numbers”, we map business results to standard HTTP codes so that clients can predict behavior just by looking at the status.

For example, a “create user” endpoint that succeeds might return 201 Created, while an attempt with a duplicate email might return 409 Conflict. The body can carry more details, but the status code already tells the high-level story.

2. The five status code families (1xx–5xx)

All HTTP status codes are divided into five ranges based on the first digit:

Status Code Families at a Glance

The table below summarizes the meaning of each family with typical usage.

Range	Category	High-level meaning	Who should act?	Typical example codes
1xx	Informational	Request received, processing continues.	Usually no action from clients; mostly used by servers and proxies.	100 Continue, 101 Switching Protocols
2xx	Success	The request was successfully received, understood, and accepted.	No error; the client can use the response data.	200 OK, 201 Created, 204 No Content
3xx	Redirection	The client must take additional action to complete the request.	Client should follow the redirect location.	301 Moved Permanently, 302 Found, 304 Not Modified, 307, 308
4xx	Client Error	There is something wrong with the request (syntax, authentication, data, etc.).	Client must fix the request before trying again.	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict
5xx	Server Error	The server failed while processing a valid request.	Server operators or developers need to investigate.	500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

3. Common status codes you should know

You will encounter dozens of status codes in RFCs and online documentation, but for daily REST work you can focus on a core set. Below is a short, practical list grouped by family.

3.1 1xx – Informational

100 Continue: The server has received the request headers and the client should continue to send the body. In most high-level REST clients you rarely handle this manually.
101 Switching Protocols: The server agrees to switch protocols (for example for WebSocket). Again, common but often hidden by your framework.

3.2 2xx – Success

200 OK: The “default” success code. Use it for successful GET, PUT, PATCH, and sometimes POST operations when nothing special happened beyond success.
201 Created: A resource was successfully created. The response should ideally include a Location header pointing to the new resource URL and a body describing it.
202 Accepted: The request was accepted for processing, but the work is happening asynchronously (e.g., background job). The client might need to poll another endpoint.
204 No Content: The request succeeded but there is no response body (for example, successful DELETE or an update with no representation needed).

3.3 3xx – Redirection

301 Moved Permanently: The resource has a new permanent URL. Clients and search engines should update bookmarks and caches.
302 Found / 307 Temporary Redirect: Temporary redirects; the resource is available at a different URL for now. 307 preserves the HTTP method.
304 Not Modified: The client’s cached copy is still valid; no response body is returned, which saves bandwidth.

3.4 4xx – Client Errors

400 Bad Request: The request is malformed or invalid. For example, missing required fields, invalid JSON, or validation errors.
401 Unauthorized: The client must authenticate (for example missing or invalid token). After correct authentication, the same request might succeed.
403 Forbidden: The client is authenticated but does not have permission to access this resource.
404 Not Found: The requested resource does not exist. Also commonly used when the server intentionally hides whether a protected resource exists.
409 Conflict: There is a conflict with the current state of the resource, for example duplicate data, version conflicts, or concurrency issues.
422 Unprocessable Entity: The server understands the request but cannot process it due to semantic errors (often used for detailed validation problems in JSON APIs).

3.5 5xx – Server Errors

500 Internal Server Error: A generic server error. Something unexpected happened (unhandled exception, bug, etc.). Avoid returning this for errors that actually are client-side.
502 Bad Gateway: A gateway or proxy received an invalid response from an upstream server. Typical in microservice or API-gateway setups.
503 Service Unavailable: The server is temporarily unable to handle the request (overload, maintenance). Often used with a Retry-After header.

4. Practical Code Examples

Let’s see how status codes appear in real HTTP calls. First, here is a simple curl example that inspects both headers and body.

curl -i -X POST "https://api.example.com/v1/users" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.user@example.com",
    "name": "New User"
  }'

If the user is successfully created, the server might respond like this:

HTTP/1.1 201 Created
Location: https://api.example.com/v1/users/123
Content-Type: application/json

{
  "id": 123,
  "email": "new.user@example.com",
  "name": "New User"
}

The 201 Created status code clearly signals that a new resource was created and its URL is given in the Location header. Clients can store this URL or navigate to it to fetch the resource later.

Now imagine that the email address already exists. A well-designed API might answer like this:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "EMAIL_ALREADY_EXISTS",
  "message": "User with this email already exists.",
  "field": "email"
}

Here the 409 Conflict status tells the client that the request is understood but cannot be completed because of a conflict in the current state. The JSON body provides structured details that front-end or other services can display to users.

5. Best Practices When Designing APIs

Using status codes consistently is part of good REST API design. Below are some practical recommendations you can apply immediately.

Use the right family first, then pick a specific code. Decide whether the result is success, redirect, client error, or server error before choosing an exact number.
Do not overload 200 OK for everything. Use the more specific codes such as 201, 204, 400, 404, 409, and 422 to make behavior clearer.
Pair status codes with meaningful error bodies. Always return a machine-readable error object (code, message, and optional details) for 4xx and 5xx responses.
Avoid leaking sensitive data. For authentication and authorization errors, consider using generic messages in 401/403 responses to avoid information leaks.
Define your status code policy in your API documentation. For each endpoint, document which codes can occur and under what conditions so clients can handle them gracefully.
Monitor 5xx rates. A rising number of 5xx responses is an early warning sign of system problems; treat it as an alert to investigate.

6. Step-by-Step Learning Plan

Memorize the five families and their meanings. Write down on a sticky note: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error. Keep it next to your monitor until it becomes natural.
Pick 2–4 representative codes from each family. For instance, 200, 201, 204, 301, 304, 400, 401, 404, 409, 500, 503. Practice describing each one in a single plain-English sentence.
Review responses from your existing APIs. Turn on verbose logging or use tools like curl -i, Postman, or Insomnia. For each endpoint, list which status codes appear and whether they make sense.
Refine your API to use clearer codes. Where everything is returning 200 or 500, adjust the implementation to use more precise 4xx codes for client issues and 5xx codes only for real server errors.
Update your API documentation. In your OpenAPI/Swagger or Markdown docs, document all expected status codes, including examples for success and error responses.
Teach your team. Share these rules with front-end and back-end developers so everyone shares the same mental model for status codes.

Additional Things to Consider

For public APIs, be extra careful with detailed error messages in 4xx and 5xx responses; always balance clarity with security.
Consider defining a standard error format used by all services, for example including fields like error, message, traceId, and details.
As your system grows, combine status-code monitoring with structured logs and distributed tracing to get a full picture of failures.

Understanding REST API Status Codes (1xx–5xx) with Simple Examples