What is the purpose of `http::StatusCode::as_u16` vs `StatusCode::as_str` for HTTP status handling?

HTTP status codes serve as the primary mechanism for conveying request outcomes in HTTP responses. The http::StatusCode type provides two distinct representations: as_u16 returns the numeric code (like 200 or 404), while as_str returns the canonical reason phrase (like "OK" or "Not Found"). These methods serve different purposes: numeric codes are essential for programmatic handling, logging, and interoperation with systems that expect numbers, while reason phrases provide human-readable context for debugging, error messages, and HTTP/1.1 response formatting. Understanding when to use each representation helps build systems that are both machine-processable and human-understandable.

Basic StatusCode Usage

use http::StatusCode;
 
fn basic_usage() {
    let status = StatusCode::OK;
    
    // Numeric representation
    let code: u16 = status.as_u16();
    assert_eq!(code, 200);
    
    // String representation (reason phrase)
    let reason: &str = status.as_str();
    assert_eq!(reason, "OK");
    
    // Display shows "200 OK"
    println!("{}", status); // "200 OK"
    
    // Debug shows more detail
    println!("{:?}", status); // "OK"
}

The two methods provide different views of the same status code.

as_u16 for Numeric Operations

use http::StatusCode;
 
fn numeric_operations() {
    let status = StatusCode::NOT_FOUND;
    
    // Use numeric code for:
    // 1. Programmatic handling
    let code = status.as_u16();
    if code >= 400 && code < 500 {
        println!("Client error: {}", code);
    }
    
    // 2. Classification
    fn classify_status(status: StatusCode) -> &'static str {
        match status.as_u16() {
            100..=199 => "informational",
            200..=299 => "success",
            300..=399 => "redirection",
            400..=499 => "client error",
            500..=599 => "server error",
            _ => "unknown",
        }
    }
    
    // 3. Logging numeric values
    struct LogEntry {
        status_code: u16,
        path: String,
    }
    
    let entry = LogEntry {
        status_code: status.as_u16(),
        path: "/api/users".to_string(),
    };
    
    // 4. Metrics collection
    fn record_metric(status: StatusCode) {
        let code = status.as_u16();
        // Metrics systems often expect numeric values
        // HISTOGRAM("http.status", code);
    }
}

Numeric codes enable programmatic classification and data processing.

as_str for Human-Readable Messages

use http::StatusCode;
 
fn string_operations() {
    let status = StatusCode::INTERNAL_SERVER_ERROR;
    
    // Use reason phrase for:
    // 1. Error messages
    fn error_message(status: StatusCode) -> String {
        format!("Request failed: {} ({})", status.as_str(), status.as_u16())
    }
    
    println!("{}", error_message(status));
    // "Request failed: Internal Server Error (500)"
    
    // 2. HTTP/1.1 response formatting
    fn format_response_line(status: StatusCode) -> String {
        format!("HTTP/1.1 {} {}", status.as_u16(), status.as_str())
    }
    
    let line = format_response_line(StatusCode::CREATED);
    assert_eq!(line, "HTTP/1.1 201 Created");
    
    // 3. User-facing messages
    fn user_message(status: StatusCode) -> &'static str {
        status.as_str()
    }
}

Reason phrases provide human context for status codes.

Understanding Reason Phrases

use http::StatusCode;
 
fn reason_phrases() {
    // Standard status codes have defined reason phrases
    let statuses = vec![
        (StatusCode::OK, "OK"),
        (StatusCode::CREATED, "Created"),
        (StatusCode::NO_CONTENT, "No Content"),
        (StatusCode::MOVED_PERMANENTLY, "Moved Permanently"),
        (StatusCode::FOUND, "Found"),
        (StatusCode::BAD_REQUEST, "Bad Request"),
        (StatusCode::UNAUTHORIZED, "Unauthorized"),
        (StatusCode::FORBIDDEN, "Forbidden"),
        (StatusCode::NOT_FOUND, "Not Found"),
        (StatusCode::INTERNAL_SERVER_ERROR, "Internal Server Error"),
        (StatusCode::BAD_GATEWAY, "Bad Gateway"),
        (StatusCode::SERVICE_UNAVAILABLE, "Service Unavailable"),
    ];
    
    for (status, expected) in statuses {
        assert_eq!(status.as_str(), expected);
    }
    
    // Custom status codes also work
    let custom = StatusCode::from_u16(299).unwrap();
    // Unknown codes return empty string for as_str
    println!("Custom status: '{}' is empty for unknown", custom.as_str());
}

Well-known status codes have canonical reason phrases; unknown codes return empty strings.

Custom Status Codes

use http::StatusCode;
 
fn custom_status_codes() {
    // Create status from u16
    let custom = StatusCode::from_u16(299).unwrap();
    
    // Numeric representation always works
    assert_eq!(custom.as_u16(), 299);
    
    // String representation is empty for unknown codes
    assert_eq!(custom.as_str(), "");
    
    // Common patterns for custom codes
    fn is_custom_status(status: StatusCode) -> bool {
        // Non-standard status codes
        !matches!(status.as_u16(),
            100..=199 |  // Informational
            200..=299 |  // Success
            300..=399 |  // Redirection
            400..=499 |  // Client Error
            500..=599    // Server Error
        )
    }
    
    // WebDAv extensions (200-level)
    let webdav_207 = StatusCode::from_u16(207).unwrap(); // Multi-Status
    let webdav_208 = StatusCode::from_u16(208).unwrap(); // Already Reported
    
    // Unofficial codes
    let unofficial_103 = StatusCode::from_u16(103).unwrap(); // Early Hints
    
    // as_str may have predefined values for some extensions
    println!("207: '{}'", webdav_207.as_str()); // "Multi-Status"
}

StatusCode handles both standard and custom numeric codes gracefully.

Display and Debug Implementations

use http::StatusCode;
 
fn display_debug() {
    let status = StatusCode::NOT_FOUND;
    
    // Display shows "404 Not Found"
    let display = format!("{}", status);
    assert_eq!(display, "404 Not Found");
    
    // Debug shows reason phrase
    let debug = format!("{:?}", status);
    assert_eq!(debug, "NOT_FOUND");
    
    // Both representations include different info
    // Display: full HTTP status line component
    // Debug: constant name
    
    // For comparison
    let created = StatusCode::CREATED;
    println!("Display: {}", created); // "201 Created"
    println!("Debug: {:?}", created);  // "CREATED"
}

Display includes both code and reason; Debug shows the constant name.

Classification Helper Methods

use http::StatusCode;
 
fn classification_helpers() {
    // StatusCode provides helper methods for classification
    let status = StatusCode::OK;
    
    // Check status classes
    assert!(status.is_success());
    assert!(!status.is_client_error());
    assert!(!status.is_server_error());
    
    // Class-based patterns
    fn handle_status(status: StatusCode) {
        if status.is_informational() {
            // 1xx: Continue with request
        } else if status.is_success() {
            // 2xx: Request succeeded
        } else if status.is_redirection() {
            // 3xx: Follow redirect
        } else if status.is_client_error() {
            // 4xx: Fix client request
            println!("Client error: {}", status.as_u16());
        } else if status.is_server_error() {
            // 5xx: Server issue
            println!("Server error: {}", status);
        }
    }
    
    // These methods use as_u16 internally
    // is_success: 200-299
    // is_client_error: 400-499
    // is_server_error: 500-599
}

Helper methods like is_success() are built on numeric ranges.

HTTP Response Formatting

use http::{StatusCode, Response, Version};
use http::header;
 
fn response_formatting() {
    // Building HTTP/1.1 response line
    fn build_status_line(version: Version, status: StatusCode) -> String {
        match version {
            Version::HTTP_09 => format!("{}", status.as_u16()), // No reason in HTTP/0.9
            Version::HTTP_10 => format!("HTTP/1.0 {} {}", status.as_u16(), status.as_str()),
            Version::HTTP_11 => format!("HTTP/1.1 {} {}", status.as_u16(), status.as_str()),
            Version::HTTP_2 => format!(":status: {}", status.as_u16()), // HTTP/2 uses pseudo-headers
            _ => format!("HTTP/1.1 {} {}", status.as_u16(), status.as_str()),
        }
    }
    
    let status_line = build_status_line(Version::HTTP_11, StatusCode::OK);
    assert_eq!(status_line, "HTTP/1.1 200 OK");
    
    // HTTP/2 doesn't use reason phrases
    // Only the numeric code in pseudo-header
    let status = StatusCode::NOT_FOUND;
    // HTTP/2: :status: 404
    println!("HTTP/2 status: {}", status.as_u16());
}

HTTP versions differ in whether they include reason phrases.

Logging and Metrics

use http::StatusCode;
use std::collections::HashMap;
 
fn logging_metrics() {
    // Numeric codes for metrics systems
    fn record_status_metric(status: StatusCode) {
        let code = status.as_u16();
        
        // Prometheus-style metrics
        let metric = format!("http_requests_total{{status=\"{}\"}}", code);
        println!("{}", metric);
        
        // Or histogram buckets
        // HTTP_STATUS_BUCKET.observe(code as f64);
    }
    
    // Structured logging
    #[derive(serde::Serialize)]
    struct LogRecord {
        status_code: u16,
        status_reason: &'static str,
        timestamp: u64,
    }
    
    fn log_response(status: StatusCode) {
        let record = LogRecord {
            status_code: status.as_u16(),
            status_reason: status.as_str(),
            timestamp: 1234567890,
        };
        println!("{}", serde_json::to_string(&record).unwrap());
    }
    
    // Aggregation by numeric code
    let mut status_counts: HashMap<u16, u32> = HashMap::new();
    for status in [StatusCode::OK, StatusCode::OK, StatusCode::NOT_FOUND] {
        *status_counts.entry(status.as_u16()).or_insert(0) += 1;
    }
    assert_eq!(status_counts.get(&200), Some(&2));
    assert_eq!(status_counts.get(&404), Some(&1));
}

Numeric codes are essential for metrics aggregation; reason phrases aid human interpretation.

Error Handling Patterns

use http::StatusCode;
 
fn error_handling() {
    // Matching on numeric values
    fn handle_response(status: StatusCode) -> Result<String, String> {
        match status.as_u16() {
            200 => Ok("Success".to_string()),
            201 => Ok("Created".to_string()),
            204 => Ok("No Content".to_string()),
            400 => Err(format!("Bad Request: {}", status.as_str())),
            401 => Err(format!("Unauthorized: {}", status.as_str())),
            403 => Err(format!("Forbidden: {}", status.as_str())),
            404 => Err(format!("Not Found: {}", status.as_str())),
            500..=599 => Err(format!("Server Error {}: {}", status.as_u16(), status.as_str())),
            _ => Err(format!("Unknown status: {}", status.as_u16())),
        }
    }
    
    // Using built-in classification
    fn classify_error(status: StatusCode) -> &'static str {
        if status.is_client_error() {
            "Fix your request"
        } else if status.is_server_error() {
            "Try again later"
        } else if status.is_success() {
            "All good"
        } else {
            "Unexpected"
        }
    }
    
    // Detailed error with both representations
    fn detailed_error(status: StatusCode, message: &str) -> String {
        format!(
            "HTTP {}: {} - {}",
            status.as_u16(),
            status.as_str(),
            message
        )
    }
    
    let error = detailed_error(StatusCode::BAD_GATEWAY, "Upstream timeout");
    assert_eq!(error, "HTTP 502: Bad Gateway - Upstream timeout");
}

Combining numeric and string representations provides comprehensive error information.

Status Code Constants

use http::StatusCode;
 
fn status_constants() {
    // StatusCode provides constants for common codes
    let ok = StatusCode::OK;                    // 200
    let created = StatusCode::CREATED;          // 201
    let accepted = StatusCode::ACCEPTED;        // 202
    let no_content = StatusCode::NO_CONTENT;    // 204
    
    let moved = StatusCode::MOVED_PERMANENTLY;  // 301
    let found = StatusCode::FOUND;              // 302
    let see_other = StatusCode::SEE_OTHER;      // 303
    let not_modified = StatusCode::NOT_MODIFIED; // 304
    
    let bad_request = StatusCode::BAD_REQUEST;   // 400
    let unauthorized = StatusCode::UNAUTHORIZED; // 401
    let forbidden = StatusCode::FORBIDDEN;       // 403
    let not_found = StatusCode::StatusCode::NOT_FOUND; // 404
    
    let internal = StatusCode::INTERNAL_SERVER_ERROR; // 500
    let bad_gateway = StatusCode::BAD_GATEWAY;  // 502
    let unavailable = StatusCode::SERVICE_UNAVAILABLE; // 503
    
    // These constants avoid typos and provide type safety
    // Compare:
    // let status = 200; // Could be any number
    // let status = StatusCode::OK; // Clearly a status code
}

Type-safe constants prevent typos and make intent clear.

Converting Between Representations

use http::StatusCode;
 
fn conversions() {
    // From u16
    let status = StatusCode::from_u16(200).unwrap();
    assert_eq!(status, StatusCode::OK);
    
    // From u16 can fail for invalid codes
    let invalid = StatusCode::from_u16(99);
    assert!(invalid.is_err());
    
    // Valid range: 100-999
    assert!(StatusCode::from_u16(99).is_err());
    assert!(StatusCode::from_u16(100).is_ok());
    assert!(StatusCode::from_u16(999).is_ok());
    assert!(StatusCode::from_u16(1000).is_err());
    
    // To u16 via as_u16
    let code: u16 = StatusCode::OK.as_u16();
    
    // Parse from string
    let from_str: StatusCode = "200".parse().unwrap();
    assert_eq!(from_str, StatusCode::OK);
    
    // Reason phrase strings also work for known codes
    let from_reason: StatusCode = "OK".parse().unwrap();
    assert_eq!(from_reason, StatusCode::OK);
}

StatusCode supports parsing from strings and conversion from u16 with validation.

HTTP/2 Considerations

use http::StatusCode;
 
fn http2_considerations() {
    // HTTP/2 doesn't transmit reason phrases
    // Only the numeric status code is sent
    
    fn build_http2_headers(status: StatusCode) -> Vec<(&'static str, String)> {
        // HTTP/2 uses :status pseudo-header with numeric code
        vec![
            (":status", status.as_u16().to_string()),
            // Reason phrase is NOT included in HTTP/2
        ]
    }
    
    let headers = build_http2_headers(StatusCode::OK);
    assert_eq!(headers[0], (":status", "200".to_string()));
    
    // HTTP/1.1 includes reason phrase
    fn build_http1_status_line(status: StatusCode) -> String {
        format!("HTTP/1.1 {} {}", status.as_u16(), status.as_str())
    }
    
    let line = build_http1_status_line(StatusCode::OK);
    assert_eq!(line, "HTTP/1.1 200 OK");
}

HTTP/2 uses only numeric codes; reason phrases are HTTP/1.1-specific.

Default and Common Values

use http::StatusCode;
 
fn defaults() {
    // Default status code is 200 OK
    let default: StatusCode = Default::default();
    assert_eq!(default, StatusCode::OK);
    
    // Common default patterns
    fn success_response() -> StatusCode {
        StatusCode::OK // Most common success
    }
    
    fn created_response() -> StatusCode {
        StatusCode::CREATED // Resource created
    }
    
    fn no_content_response() -> StatusCode {
        StatusCode::NO_CONTENT // Success with no body
    }
    
    fn bad_request(message: &str) -> (StatusCode, String) {
        (StatusCode::BAD_REQUEST, message.to_string())
    }
    
    fn not_found(resource: &str) -> (StatusCode, String) {
        (StatusCode::NOT_FOUND, format!("{} not found", resource))
    }
    
    fn internal_error() -> StatusCode {
        StatusCode::INTERNAL_SERVER_ERROR
    }
}

StatusCode::OK is the default, reflecting the most common response.

Real-World Example: Web Framework Handler

use http::StatusCode;
use http::header;
 
struct HttpResponse {
    status: StatusCode,
    headers: Vec<(&'static str, String)>,
    body: Option<String>,
}
 
impl HttpResponse {
    fn new(status: StatusCode) -> Self {
        HttpResponse {
            status,
            headers: Vec::new(),
            body: None,
        }
    }
    
    fn with_body(status: StatusCode, body: String) -> Self {
        HttpResponse {
            status,
            headers: vec![("Content-Type", "application/json".to_string())],
            body: Some(body),
        }
    }
    
    fn to_http1_1(&self) -> String {
        let mut response = format!(
            "HTTP/1.1 {} {}\r\n",
            self.status.as_u16(),
            self.status.as_str()
        );
        
        for (name, value) in &self.headers {
            response.push_str(&format!("{}: {}\r\n", name, value));
        }
        
        if let Some(body) = &self.body {
            response.push_str(&format!("Content-Length: {}\r\n", body.len()));
            response.push_str("\r\n");
            response.push_str(body);
        } else {
            response.push_str("\r\n");
        }
        
        response
    }
}
 
fn handle_request(path: &str) -> HttpResponse {
    match path {
        "/health" => HttpResponse::new(StatusCode::OK),
        "/api/users" => HttpResponse::with_body(
            StatusCode::OK,
            r#"[{"id": 1, "name": "Alice"}]"#.to_string()
        ),
        "/api/users/1" => HttpResponse::with_body(
            StatusCode::OK,
            r#"{"id": 1, "name": "Alice"}"#.to_string()
        ),
        _ => HttpResponse::with_body(
            StatusCode::NOT_FOUND,
            r#"{"error": "Not found"}"#.to_string()
        ),
    }
}

Web frameworks use both numeric and string representations when formatting responses.

Real-World Example: Status Logging Middleware

use http::StatusCode;
 
struct AccessLog {
    method: String,
    path: String,
    status_code: u16,
    status_reason: &'static str,
    duration_ms: u64,
}
 
impl AccessLog {
    fn to_json(&self) -> String {
        format!(
            r#"{{"method":"{}","path":"{}","status":{},"reason":"{}","duration":{}}}"#,
            self.method, self.path, self.status_code, self.status_reason, self.duration_ms
        )
    }
    
    fn to_common_log_format(&self) -> String {
        // Common Log Format: host ident authuser date request status bytes
        format!(
            "- - - [timestamp] \"{} {}\" {} -",
            self.method, self.path, self.status_code
        )
    }
}
 
fn logging_middleware(status: StatusCode, method: &str, path: &str, duration_ms: u64) {
    let log = AccessLog {
        method: method.to_string(),
        path: path.to_string(),
        status_code: status.as_u16(),
        status_reason: status.as_str(),
        duration_ms,
    };
    
    // Structured logging for log aggregation
    println!("{}", log.to_json());
    
    // Human-readable for console
    println!("[{}] {} {} - {} ({})", 
        log.duration_ms, log.method, log.path, log.status_code, log.status_reason);
}
 
fn example_logging() {
    logging_middleware(StatusCode::OK, "GET", "/api/users", 15);
    // Output: [15] GET /api/users - 200 (OK)
    
    logging_middleware(StatusCode::NOT_FOUND, "POST", "/api/unknown", 3);
    // Output: [3] POST /api/unknown - 404 (Not Found)
}

Logs benefit from both numeric codes (for parsing) and reason phrases (for human readers).

Synthesis

Method comparison:

| Method | Return Type | Use Case | |--------|-------------|----------| | as_u16() | u16 | Programmatic handling, metrics, HTTP/2 | | as_str() | &'static str | Human-readable messages, HTTP/1.1, debugging |

When to use each:

| Scenario | Preferred Method | Reason | |----------|-----------------|--------| | Metrics collection | as_u16() | Numeric aggregation | | Status classification | as_u16() | Range-based matching | | HTTP/2 responses | as_u16() | HTTP/2 doesn't use reason phrases | | Error messages | as_str() | Human context | | HTTP/1.1 response line | Both | "200 OK" format | | Log files | Both | Machine parseable + readable |

Status code ranges:

| Range | Class | Example Codes | |-------|-------|----------------| | 100-199 | Informational | 100 Continue, 101 Switching Protocols | | 200-299 | Success | 200 OK, 201 Created, 204 No Content | | 300-399 | Redirection | 301 Moved Permanently, 304 Not Modified | | 400-499 | Client Error | 400 Bad Request, 404 Not Found | | 500-599 | Server Error | 500 Internal Server Error, 503 Unavailable |

Key insight: The as_u16() and as_str() methods serve complementary purposes in HTTP status handling. The numeric representation (as_u16()) is essential for programmatic processing—classifying responses, aggregating metrics, building HTTP/2 headers, and routing error handling logic. The string representation (as_str()) provides the canonical reason phrase defined in HTTP specifications, adding human-readable context for error messages, log files, and HTTP/1.1 response formatting. The http::StatusCode type gives you both representations with type safety, ensuring you never accidentally use an invalid status code. For comprehensive error information, combine both: format!("HTTP {}: {}", status.as_u16(), status.as_str()) produces "HTTP 404: Not Found", providing both the machine-processable code and human context in a single message.

Loading page…

What is the purpose of http::StatusCode::as_u16 vs StatusCode::as_str for HTTP status handling?

Basic StatusCode Usage

as_u16 for Numeric Operations

as_str for Human-Readable Messages

Understanding Reason Phrases

Custom Status Codes

Display and Debug Implementations

Classification Helper Methods

HTTP Response Formatting

Logging and Metrics

Error Handling Patterns

Status Code Constants

Converting Between Representations

HTTP/2 Considerations

Default and Common Values

Real-World Example: Web Framework Handler

Real-World Example: Status Logging Middleware

Synthesis

What is the purpose of http::StatusCode::as_u16 vs StatusCode::as_str for HTTP status handling?

Basic StatusCode Usage

as_u16 for Numeric Operations

as_str for Human-Readable Messages

Understanding Reason Phrases

Custom Status Codes

Display and Debug Implementations

Classification Helper Methods

HTTP Response Formatting

Logging and Metrics

Error Handling Patterns

Status Code Constants

Converting Between Representations

HTTP/2 Considerations

Default and Common Values

Real-World Example: Web Framework Handler

Real-World Example: Status Logging Middleware

Synthesis

What is the purpose of `http::StatusCode::as_u16` vs `StatusCode::as_str` for HTTP status handling?

What is the purpose of `http::StatusCode::as_u16` vs `StatusCode::as_str` for HTTP status handling?