HTTP Status Codes — 2xx, 3xx, 4xx, 5xx

2xx Success Codes: Confirming Desired Outcomes

The 2xx range signifies that the request was successfully received, understood, and accepted by the server. When an API returns a 200 OK, it implies a standard success where the payload contains the requested data or result. However, the protocol offers more nuance; for instance, a 201 Created is mandatory when a resource is successfully initialized via a POST request, explicitly informing the client that a new URI exists for the item. The 204 No Content code is equally critical for operations like deletions or updates where no body response is required, preventing the client from attempting to parse an empty payload. Reasoning for these choices hinges on transparency; the client must know exactly what happened to the state of the system so it can update its local representation accordingly without guesswork.

// 200 OK: General success with body content
// 201 Created: New resource successfully generated at a specific URI
// 204 No Content: Operation successful, but no response body necessary

const handlePost = (resource) => {
  // Simulate database creation
  return { status: 201, location: '/users/123', body: resource };
};

3xx Redirection Codes: Navigating Resource Transitions

Redirection status codes exist to inform the client that further action is required to complete the request. These codes function as a bridge, allowing the server to maintain clean URI structures while evolving the API over time. A 301 Moved Permanently is the definitive instruction to the client that a resource has a new, permanent location, effectively updating any cached links. Conversely, a 302 Found or 307 Temporary Redirect indicates that the resource is available at a different URI for the moment, but the client should continue using the original URI for future requests. The underlying principle here is resource mobility; by using these codes, you decouple the client's internal references from your server's current architectural implementation, ensuring that breaking changes are mitigated gracefully without losing your traffic.

// 301 Moved Permanently: URI has changed for good
// 307 Temporary Redirect: Use this location just for now

const handleOldEndpoint = () => {
  // Redirect client to the new version of the API
  return { status: 301, headers: { 'Location': '/v2/resources' } };
};

4xx Client Error Codes: Identifying Invalid Requests

The 4xx range indicates that the client has made an error, such as providing a malformed request or attempting to access restricted data. A 400 Bad Request is the catch-all for syntactical issues, such as missing required fields or invalid data types, while 401 Unauthorized signals that authentication credentials are missing or invalid. Furthermore, 403 Forbidden is used when the server understands the request but refuses to authorize it based on the user's lack of permission. A 404 Not Found is perhaps the most famous, signaling that no resource exists at the given URI. Reasoning through these is simple: if the error is the fault of the sender, you must use 4xx codes to signal that repeating the exact same request without modification will only result in the same failure.

// 400 Bad Request: Malformed JSON payload
// 401 Unauthorized: Invalid or missing authentication tokens
// 404 Not Found: Resource lookup failed

const findResource = (id) => {
  if (!id) return { status: 400, error: 'ID is required' };
  // Database lookup simulation
  return { status: 404, error: 'Resource not found' };
};

5xx Server Error Codes: Handling Internal Failures

When a 5xx status code is returned, the implication is that the server itself is at fault. These codes act as a diagnostic signal indicating that while the request appears valid, the server encountered an unexpected condition—such as a database timeout, a configuration error, or an unhandled exception—that prevented fulfillment. A 500 Internal Server Error is the generic notification for any unexpected crash, while 503 Service Unavailable suggests that the server is temporarily overloaded or undergoing maintenance. The reasoning for these codes is critical for observability; they distinguish transient infrastructure issues from permanent client-side errors. When you trigger a 5xx, you are telling the client that the fault is not theirs and that a retry at a later time might eventually yield a successful result once the server recovers.

// 500 Internal Server Error: Unexpected exception
// 503 Service Unavailable: Server is overloaded

const processTask = () => {
  try {
    throw new Error('Database connection failed');
  } catch (e) {
    // Log error internally and notify client of server fault
    return { status: 500, message: 'Internal Server Error' };
  }
};

Strategic Application: Choosing the Correct Code

Selecting the correct HTTP status code requires a deep understanding of the intent behind every endpoint. You should always prioritize the most specific code available; for example, do not use 400 if the issue is strictly related to authentication, as 401 is the purpose-built standard. Additionally, consider the side effects of your operations. If an operation is idempotent, your status codes must accurately reflect whether the resource state changed or remained static. When debugging, these codes are your first line of defense, allowing you to categorize logs into client-driven errors and server-side incidents instantly. Consistency is paramount; by adhering strictly to these conventions, you allow client-side libraries to implement automatic retry logic for 5xx errors while surfacing helpful input validation feedback to users when they trigger 4xx errors.

// Consistent status code mapping for API resilience

const apiResponse = (errorType) => {
  switch(errorType) {
    case 'AUTH': return { status: 401 };
    case 'DB_DOWN': return { status: 503 };
    default: return { status: 200 };
  }
};

Interview questions

All REST API Design interview questions →

Check yourself

Take the full REST API Design quiz →