What are HTTP status codes?

observability

13 November 2024

Think of them as three-digit notes from the server that let you know how a client’s request turned out. Did it succeed? Is there an error? Maybe it needs a follow-up? Each code gives a quick answer, letting you know where things stand without digging deeper. Knowing how to interpret these codes? That’s essential for running a stable app and catching issues before they snowball.

In this guide

Complete Guide to HTTP Status Codes
- Informational (1xx) Responses
- Success (2xx) Responses
- Redirection (3xx) Responses
- Client Error (4xx) Responses
- Server Error (5xx) Responses
Managing Status Codes Across Environments
Testing and Implementation Patterns
Best Practices and Real-world Solutions
Getting Started with Upsun

Let's break down these status codes by category, then dive into how to handle them effectively across environments.

Status codes are grouped into five categories, each telling you something specific about what happened with a request:

1xx: Informational responses

These codes tell you "I'm working on it." They're less common but important for complex operations:

100 Continue: The server got your headers and likes what it sees. Keep sending the rest of the request.
101 Switching Protocols: Server's agreeing to switch protocols (like upgrading from HTTP to WebSocket).
102 Processing: For complex requests that need extra time - server's saying "Still working on it!"
103 Early Hints: Server's giving you a heads up about what's coming, often used for resource preloading.

2xx: Success responses

These are the "all good" signals:

200 OK: The golden standard - everything worked exactly as it should.
201 Created: Success! A new resource was created (common after POST/PUT requests).
202 Accepted: Request looks good but isn't finished yet - useful for long-running tasks.
203 Non-Authoritative Information: Success, but the data might have been modified by a proxy.
204 No Content: All good, but there's nothing to send back.
206 Partial Content: Here's part of what you asked for (great for streaming and large downloads).

Additional important 2xx responses

205 Reset Content: Client should reset the document view
207 Multi-Status (WebDAV): Multiple status codes for single request
208 Already Reported: Avoid duplicate enumeration
226 IM Used: Server has fulfilled request for the resource

3xx: Redirection

These codes say "Look somewhere else":

301 Moved Permanently: Resource has a new permanent home.
302 Found: Resource is temporarily somewhere else.
304 Not Modified: Your cached version is still good (saves bandwidth).
307 Temporary Redirect: Like 302, but keeps your original request method.
308 Permanent Redirect: Like 301, but keeps your original request method.

Understanding redirect behavior:

300 Multiple Choices: Server offers different formats of requested resource
305 Use Proxy (Deprecated but important to know): Resource must be accessed through proxy
306 Switch Proxy: No longer used but reserved

These redirect codes are crucial for SEO and application architecture decisions.

4xx: Client errors

When the client (that's you) did something unexpected:

400 Bad Request: Server can't understand what you sent.
401 Unauthorized: You need to authenticate first.
403 Forbidden: You're authenticated but don't have permission.
404 Not Found: The resource isn't here.
405 Method Not Allowed: That HTTP method isn't allowed here.
408 Request Timeout: Your request took too long.
413 Payload Too Large: Request body exceeds server limits
415 Unsupported Media Type: Server doesn't support the content type sent
422 Unprocessable Content: Request syntax correct but semantically invalid
423 Locked: Resource is locked
428 Precondition Required: Server requires conditional request
429 Too Many Requests: Slow down! You're making too many requests.

Additional important client errors:

451 Unavailable for legal reasons: Resource legally restricted

Critical 4xx codes for API development:

409 Conflict: Request conflicts with server's state (common in PUT operations)
411 Length Required: Server requires Content-Length header
412 Precondition Failed: Server doesn't meet preconditions from client
414 URI Too Long: Request URL exceeds server limits
416 Range Not Satisfiable: Requested range cannot be fulfilled

5xx: Server errors

When it's the server's fault:

500 Internal Server Error: An error occurred on the server side.
501 Not Implemented: Server doesn't support required functionality
502 Bad Gateway: Got a bad response from an upstream server.
503 Service Unavailable: Server can't handle requests right now.
504 Gateway Timeout: Upstream server took too long to respond.
507 Insufficient Storage: Server can't store data needed
508 Loop Detected: Server detected infinite loop while processing
511 Network Authentication Required: Client needs to authenticate to network

Common non-standard status codes

You might also encounter these unofficial but widely used codes:

450 Blocked by Windows Parental Controls: Used by Microsoft
499 Client Closed Request: Used by nginx when client disconnects
520 Unknown Error: Used by Cloudflare for unrecognized server responses

Implementation considerations

When implementing status code handling, consider these factors:

Cache implications of different status codes
Security implications of detailed error messages
Load balancer and proxy interactions
Client retry behavior expectations

Common patterns and antipatterns

Good practices:

Use specific error codes instead of generic 500s
Include Retry-After headers with 429 and 503 responses
Maintain consistent error formats across all responses
Log detailed errors server-side while sending safe client messages

Antipatterns to avoid:

Returning 200 OK with error messages in the body
Using 404 for authentication failures
Sending sensitive information in error responses
Inconsistent error formats across services

From theory to practice: Managing status codes across environments

While knowing each status code's meaning is essential, the real challenge lies in implementing them effectively. Let's explore how to handle these codes in production-grade applications.

Why consistent status code handling matters

Now that we understand the full range of status codes, let's tackle the real challenge: keeping them consistent across environments. Status codes and response messages should be straightforward, giving clear signals about the outcome of client request processing and server responses. But too often, developers find that what works in development goes haywire in production—flooding logs with unexpected error codes. When handling of response codes and request processing is inconsistent, it leads to poor user experience, complicates debugging, and introduces security concerns.

For developers, this means wasted time tracing request failures, network errors, and timeout errors and facing unpredictable responses across environments. As applications grow, ensuring consistent, informative status codes becomes essential to keep everything running smoothly. In this guide, we’ll explore practical strategies to help you handle status codes effectively, making your applications more resilient and your debugging process far smoother.

Understanding response codes and error handling in web service APIs

With our reference guide in mind, let's look at how these status codes behave in practice. Like environment variables, their behavior can vary dramatically depending on context:

In development, you might get a 200 Success
In staging, the same endpoint returns a 404 Not Found
In production, it unexpectedly throws a 500 Error

Each of these codes (as we saw in our reference) means something specific, but their inconsistency across environments signals deeper issues that need addressing.

Managing status codes across development and production environments

A common issue is when an origin server returns a different status code in production than in development—like a 404 Not Found instead of a 200 OK—often due to differences in file permissions, database access, or other environment factors.

The challenge isn’t just reading error responses; it’s figuring out why a 404 appears in production while a 200 works in development. This gap usually signals underlying issues in request handling or permissions between environments.

Common error situations across environments

Handling unexpected errors and error responses in production

Unexpected server errors and 5xx error responses in production can be especially frustrating since they're often impossible to replicate locally. These server errors can stem from database issues to configuration mishaps, making debugging tough.

You’ve tested thoroughly. Staging checks out. Yet, production still returns unexpected status codes. Sound familiar? It’s not just about the codes themselves—it’s about how your app behaves differently across environments.

Managing response codes and request processing in web service APIs and upstream servers

Modern web service APIs often involve multiple services communicating through request messages and response codes. Each service can return its own status codes, and these need to make sense not just individually, but as part of the whole system. A 200 from your auth service doesn't help if your resource service is returning 403s.

Testing error responses and handling request failures across environments

Setting up test scenarios for different response codes and error conditions is essential but challenging when dealing with asynchronous operations and concurrent requests. Manually triggering errors is risky, mocks lack real-world nuance, and feature flags add complexity.

So how do you test error handling without breaking things? Common approaches include:

Manually causing errors (risky)
Mocking responses (unreliable)
Using feature flags (complex)

Authentication and user experience: Beyond basic status codes

Instead of listing every possible status code, let's focus on the ones that actually impact your daily work and how to handle them effectively:

Authentication flow (401 vs 403)

As we saw in our status code reference, 401 and 403 serve distinct purposes. In practice, here's how to implement them correctly:

# The common pattern
@app.route('/api/resource')
def get_resource():
    if not authenticated:
        return {'message': 'Login required'}, 401  # Not logged in
    if not authorized:
        return {'message': 'Access denied'}, 403   # Logged in but not allowed

The difference seems simple, but in multi-service architectures, getting this wrong can lead to confusing user experiences and hard-to-debug issues.

Handling server errors and timeout conditions effectively

When your service hits issues or encounters server overload, returning a 503 Service Unavailable with a Retry-After header is far more useful than a generic 500 error—it tells the client the issue is temporary and when they can retry.

Unhelpful example

# Don't do this
@app.route('/api/data')
def get_data():
    try:
        # Something breaks
        return {'error': 'Something went wrong'}, 500  # Unhelpful!

Better approach

# Do this instead
@app.route('/api/data')
def get_data():
    if service_overloaded():
        return {
            'error': 'Service temporarily unavailable',
            'retry_after': '30 seconds'
        }, 503  # Clear, actionable response

Progressive enhancement is a solid approach for handling status codes. Start with the basics, like handling 200 OK responses, and then gradually layer in more complexity—such as handling 401 Unauthorized or 503 Service Unavailable.

The reality of environment differences

Here's what most status code guides don't tell you: even a perfectly implemented status code system can behave differently across environments. When your origin server returns different response codes in production than in development, it often points to deeper issues in request processing and environment configuration.It's not just about getting the codes right - it's about understanding why:

Production enforces stricter security rules that can trigger unexpected 401s and 403s
Staging environments might lack complete data, causing 404s where you expect 200s
Development environments often use mocks, hiding real-world complexity

This environmental inconsistency isn't just an inconvenience - it's a fundamental challenge that affects every aspect of your application's reliability. Just as environment variables need careful management across contexts, status codes require a systematic approach to ensure consistent behavior.

This is where environment cloning becomes invaluable. With Upsun, you can create exact copies of your production environment, allowing you to:

Test real status code behavior without risk
Debug inconsistencies in isolation
Validate error handling across environments

Real-world example: Handling environment-specific responses

# Real-world example: Handling environment-specific responses
class EnvironmentAwareHandler:
    def handle_response(self, environment, response):
        if environment == 'production':
            # Production needs careful error logging
            if response.status_code >= 500:
                notify_ops_team(response)
                return fallback_response()
                
        elif environment == 'staging':
            # Staging can show more detailed errors
            if response.status_code >= 400:
                return detailed_error_response(response)
                
        # Development shows maximum debug info
        return development_response(response)

Making testing reliable with environment cloning

Testing error responses requires understanding both the meaning of each status code (as covered in our reference) and their behavior across environments. Let's look at practical testing strategies for different categories:

2xx codes: Verify successful operations
3xx codes: Validate redirect chains and caching
4xx codes: Test authentication and authorization flows
5xx codes: Simulate server issues and recovery

The traditional approach to testing response messages and error handling is fundamentally flawed: you either risk breaking production or rely on incomplete mocks. But what if you could test with production-perfect environments without the risk?

With Upsun, you can safely clone your production environment to test the EnvironmentAwareHandler. Specifically, you can leverage the PLATFORM_ENVIRONMENT_TYPE environment variable to distinguish between environments in your implementation. This allows you to:

Create exact replicas of your production environment in seconds
Test real error scenarios with actual data and configurations
Validate status code behavior across different conditions
Dispose of test environments when done, eliminating cleanup overhead

This is where Upsun's instant environment cloning transforms the testing process. Instead of guessing how your error handling might behave in production, you can:

Create exact replicas of your production environment in seconds
Test real error scenarios with actual data and configurations
Validate status code behavior across different conditions
Dispose of test environments when done, eliminating cleanup overhead

From testing to implementation: Real-world patterns

Now that we understand how to test effectively, let's explore patterns that work in production environments. These approaches have been battle-tested across different scales and architectures.

Pattern 1: Progressive enhancement

Start with basic handling and add complexity as needed:

async function fetchData(endpoint) {
    try {
        const response = await fetch(endpoint);

        switch (response.status) {
            case 200:
                return await response.json();
            case 401:
                // Handle authentication
                return await refreshAndRetry(endpoint);
            case 503:
                // Handle temporary outage
                return await retryWithBackoff(endpoint);
            default:
                // Log unexpected codes
                logUnexpectedStatus(response.status);
                throw new Error('Unexpected response');
        }
    } catch (error) {
        handleError(error);
    }
}

Pattern 2: Environment-specific behavior

Different environments might need different handling:

const statusHandlers = {
    development: {
        404: showDetailedNotFound,
        500: showDebugInfo
    },
    production: {
        404: showFriendlyNotFound,
        500: logAndNotify
    }
};

Solving common status code challenges

Development teams face similar challenges when managing status codes across environments. Let's look at how to address them systematically:

Inconsistent behavior across environments is often the first hurdle. Instead of letting each environment handle errors differently, establish a standardized approach. Configure your error responses consistently, implement uniform handling patterns, and most importantly, monitor how status codes behave across different environments.

Upsun's approach to environment management addresses these challenges head-on. Instead of maintaining separate, potentially divergent environments, you can create instant clones of your production setup. This means your testing environments aren't just similar to production - they're exact copies, down to the last configuration detail.

Testing error scenarios becomes much more manageable when you have isolated environments. Rather than risking production stability, create dedicated test environments that perfectly mirror your production setup. This allows you to implement chaos testing safely - deliberately triggering error conditions to validate your handling - without affecting real users.

Traditional testing often fails to replicate production conditions accurately. Upsun's environment cloning changes this dynamic. You can create a new, isolated environment for each test scenario, complete with real data and configurations, then dispose of it when done. This means no more guessing about how your error handling will behave in production.

# Example: Testing status codes across cloned environments
class StatusCodeTester:
    def __init__(self, base_url, environment_type):
        self.base_url = base_url
        self.environment = environment_type
        self.error_patterns = {}
 
    def test_endpoint(self, path, expected_status):
        """
        Test endpoints across different environments without risk
        This is especially valuable with Upsun's instant environment cloning
        """
        try:
            response = make_request(f"{self.base_url}{path}")
            self.error_patterns[path] = response.status_code

            if response.status_code != expected_status:
                log_environment_difference(
                    path=path,
                    expected=expected_status,
                    actual=response.status_code,
                    environment=self.environment
                )

        except Exception as e:
            handle_test_failure(e, self.environment)

    def compare_environments(self, production_patterns):
        """
        Compare status codes between environments
        Useful when validating cloned environments
        """
        differences = []
        for path, prod_status in production_patterns.items():
            if self.error_patterns.get(path) != prod_status:
                differences.append({
                    'path': path,
                    'production': prod_status,
                    'current_env': self.error_patterns.get(path),
                    'environment': self.environment
                })
        return differences

Debugging production issues requires visibility. Set up comprehensive monitoring that tracks status code patterns over time. When unexpected codes appear, ensure you're logging enough context to understand what went wrong. This monitoring becomes even more valuable when you can compare patterns across cloned environments, spotting discrepancies before they affect users.

Understanding production behavior

Debugging status codes in production requires a systematic approach. Start by tracking request patterns, response times, and error status codes over time - this helps identify normal behavior versus anomalies. Combine this with detailed logging of unexpected codes, ensuring you capture enough context to understand what triggered them. Finally, set up alerts that notify you of concerning patterns before they impact users.

With Upsun's environment cloning, you can reproduce these patterns in isolated environments, making it safer to debug and test fixes without affecting production users.

Principles of effective status code handling

Let's move beyond theory to practical implementation. The key to effective status code handling isn't just about returning the right codes - it's about building a system that's clear, consistent, and maintainable.

Start with clarity: Each response status code and error code should serve a specific purpose in your request processing. Instead of defaulting to generic 500 errors, use precise codes that communicate exactly what went wrong. This might mean using 429 for rate limiting, 503 for temporary outages, or 422 for validation failures.

Documentation becomes your team's shared language. When everyone knows exactly which codes to expect from each endpoint, debugging becomes collaborative rather than confrontational. This is especially crucial for those edge cases that only appear in production.

Building for scale and reliability.

As your application grows, your status code handling needs to evolve. Focus on:

Monitoring and visibility

Track patterns across environments
Set up alerts for unexpected behaviors
Maintain consistent logging

Performance and stability

Implement rate limiting (429) for API protection
Handle service degradation (503) gracefully
Use proper caching (304) for optimization

This systematic approach to error handling and request processing, combined with Upsun's environment management, helps maintain reliability as your application scales.

The Path Forward

As you review your status code handling, consider how closely it aligns with best practices. Are you returning specific codes like 429 Too Many Requests or 503 Service Unavailable when needed? Can you safely test error scenarios? Do you have visibility into status code patterns across environments?

Bringing it all together: Status codes in modern web development

The challenge with status codes isn’t knowing what they mean—any developer can see that a 404 is “not found.” The real challenge is managing them effectively across complex, multi-environment applications to ensure consistent behavior and robust error handling.

Key takeaways:

Different environments require different approaches to handling request processing, error responses, and status code monitoring
Testing error scenarios requires a systematic, environment-aware approach
Proper monitoring and pattern recognition help prevent issues before they impact users

Status codes are your application's nervous system, sending vital signals about its health and behavior across environments. When properly implemented, they provide clear insights for debugging, monitoring, and maintaining stability. The key isn't achieving perfect status code handling—it's building a system that's resilient and consistent across all environments.

This is where Upsun's environment management becomes transformative. By providing instant, accurate environment clones, you can validate your status code handling with confidence, knowing that what works in your test environment will behave the same way in production.

Getting started with better status code handling

Armed with both our comprehensive reference and practical implementation patterns, you're ready to improve your application's status code handling. Think of status codes as more than just responses—they're a critical part of your app's communication system that needs careful management across development, staging, and production.

Ready to enhance your status code handling? Here's your action plan:

Reference: Keep our status code guide handy for choosing the right codes
Implementation: Use our patterns for consistent handling across environments
Testing: Leverage Upsun's environment cloning to validate behavior
Monitoring: Track patterns to catch issues before they impact users

Want to test your status code handling in a production-grade environment? Try Upsun’s free trial*, where you can:

Test error handling and asynchronous operations safely with instant environment cloning
Monitor status codes across different environments
Implement proper error handling without risking production
Validate your implementation in a real-world setting

Start a free trial

*Free trial provides ample resources to test and evaluate Upsun in a production-grade environment.