HTTP Status Codes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

// 200 OK - Standard success with content
app.get('/users/:id', async (req, res) => {
    const user = await userRepository.findById(req.params.id);
    if (!user) return res.status(404).json({ error: 'Not Found' });
    
    res.status(200).json(user); // 200 is default, but explicit is clearer
});
 
 
// 201 Created - Resource created, include Location header
app.post('/users', async (req, res) => {
    const user = await userRepository.create(req.body);
    
    res.status(201)
       .header('Location', `/users/${user.id}`)
       .json({
           id: user.id,
           name: user.name,
           createdAt: user.createdAt,
           _links: {
               self: { href: `/users/${user.id}` }
           }
       });
});
 
 
// 202 Accepted - Async operation started (polling pattern)
app.post('/reports/generate', async (req, res) => {
    const job = await jobQueue.enqueue('generate-report', req.body);
    
    res.status(202).json({
        message: 'Report generation started',
        jobId: job.id,
        status: 'pending',
        estimatedTime: '30 seconds',
        checkStatus: `/jobs/${job.id}`,
        _links: {
            status: { href: `/jobs/${job.id}` },
            cancel: { href: `/jobs/${job.id}`, method: 'DELETE' }
        }
    });
});
 
 
// 204 No Content - Success, but nothing to return
app.delete('/users/:id', async (req, res) => {
    await userRepository.delete(req.params.id);
    res.status(204).send(); // No body, no .json()
});
 
// Also good for PUT/PATCH when client doesn't need echo
app.put('/settings', async (req, res) => {
    await settingsRepository.replace(req.user.id, req.body);
    res.status(204).send(); // Client sent the data, knows what it is
});
 
 
// 206 Partial Content - Range requests (video streaming, large files)
app.get('/videos/:id', async (req, res) => {
    const video = await videoRepository.findById(req.params.id);
    const range = req.headers.range;
    
    if (range) {
        const [start, end] = parseRange(range, video.size);
        const stream = createReadStream(video.path, { start, end });
        
        res.status(206)
           .header('Content-Range', `bytes ${start}-${end}/${video.size}`)
           .header('Accept-Ranges', 'bytes')
           .header('Content-Length', end - start + 1)
           .header('Content-Type', 'video/mp4');
        
        stream.pipe(res);
    } else {
        // Full file request
        res.sendFile(video.path);
    }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

// 301 Moved Permanently - Resource has a new permanent home
// Browsers/clients should update bookmarks and caches
app.get('/api/v1/users/:id', (req, res) => {
    // Old API version, permanently redirect to v2
    res.redirect(301, `/api/v2/users/${req.params.id}`);
});
 
 
// 308 Permanent Redirect - Preserves HTTP method
// Use this when moving PUT/POST/DELETE endpoints
app.all('/old-endpoint', (req, res) => {
    res.redirect(308, '/new-endpoint');
    // If client sent POST, they'll POST to /new-endpoint
});
 
 
// 303 See Other - After form submission (POST-Redirect-GET pattern)
app.post('/orders', async (req, res) => {
    const order = await orderService.create(req.body);
    
    // Redirect to the created order (prevent refresh = resubmit)
    res.redirect(303, `/orders/${order.id}`);
    // Client will GET /orders/{id}, which is safe to refresh
});
 
 
// 304 Not Modified - Conditional request, use cache
app.get('/products/:id', async (req, res) => {
    const product = await productRepository.findById(req.params.id);
    const etag = generateETag(product);
    
    // Check if client's cached version is still valid
    if (req.headers['if-none-match'] === etag) {
        return res.status(304).send(); // Use your cached version
    }
    
    res.header('ETag', etag)
       .json(product);
});
 
 
// 307 Temporary Redirect - Temporary, but preserve method
// Use for maintenance, A/B testing, or temporary alternatives
app.all('/payments', (req, res) => {
    if (maintenanceMode) {
        // Temporarily redirect to backup payment processor
        res.redirect(307, 'https://backup.payments.example.com/process');
        // Original POST stays POST
    } else {
        // Normal processing...
    }
});
 
 
// Practical: Canonical URL redirect
app.get('/users/:id', async (req, res) => {
    const user = await userRepository.findById(req.params.id);
    
    if (!user) return res.status(404).json({ error: 'Not Found' });
    
    // If accessed by numeric ID but we prefer slug
    const canonicalPath = `/users/${user.slug}`;
    if (req.path !== canonicalPath) {
        return res.redirect(301, canonicalPath);
    }
    
    res.json(user);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

// 400 Bad Request - Malformed input
app.post('/users', (req, res) => {
    // Check for syntactically invalid JSON (usually caught by middleware)
    // or missing required fields
    if (!req.body.email || !req.body.name) {
        return res.status(400).json({
            error: 'BAD_REQUEST',
            message: 'Missing required fields',
            details: {
                email: !req.body.email ? 'Required' : undefined,
                name: !req.body.name ? 'Required' : undefined
            }
        });
    }
});
 
 
// 401 Unauthorized - Not authenticated
// Always include WWW-Authenticate header per RFC
app.use('/protected/*', (req, res, next) => {
    if (!req.headers.authorization) {
        return res.status(401)
            .header('WWW-Authenticate', 'Bearer realm="api"')
            .json({
                error: 'UNAUTHORIZED',
                message: 'Authentication required',
                authType: 'Bearer token'
            });
    }
    next();
});
 
 
// 403 Forbidden - Authenticated but not allowed
app.delete('/users/:id', requireAuth, async (req, res) => {
    const targetUser = await userRepository.findById(req.params.id);
    
    // User exists but requester can't delete them
    if (req.user.role !== 'admin' && req.user.id !== req.params.id) {
        return res.status(403).json({
            error: 'FORBIDDEN',
            message: 'You do not have permission to delete this user',
            required: 'admin role or own account'
        });
    }
    
    await userRepository.delete(req.params.id);
    res.status(204).send();
});
 
 
// 404 Not Found - Resource doesn't exist
app.get('/users/:id', async (req, res) => {
    const user = await userRepository.findById(req.params.id);
    
    if (!user) {
        return res.status(404).json({
            error: 'NOT_FOUND',
            message: `User with ID '${req.params.id}' not found`,
            resource: 'User',
            identifier: req.params.id
        });
    }
    
    res.json(user);
});
 
 
// 409 Conflict - State conflict
app.post('/users', async (req, res) => {
    const existing = await userRepository.findByEmail(req.body.email);
    
    if (existing) {
        return res.status(409).json({
            error: 'CONFLICT',
            message: 'A user with this email already exists',
            field: 'email',
            conflictingResource: `/users/${existing.id}`
        });
    }
    // ... create user
});
 
 
// 422 Unprocessable Entity - Valid syntax but semantic errors
app.post('/orders', async (req, res) => {
    // JSON is valid, but business rules violated
    const errors = [];
    
    if (req.body.quantity < 1) {
        errors.push({ field: 'quantity', message: 'Must be at least 1' });
    }
    if (req.body.discount > req.body.subtotal) {
        errors.push({ field: 'discount', message: 'Cannot exceed subtotal' });
    }
    
    if (errors.length > 0) {
        return res.status(422).json({
            error: 'VALIDATION_FAILED',
            message: 'Request failed validation',
            validationErrors: errors
        });
    }
});
 
 
// 429 Too Many Requests - Rate limiting
app.use(rateLimit({
    windowMs: 60 * 1000, // 1 minute
    max: 100,
    handler: (req, res) => {
        res.status(429)
           .header('Retry-After', '60')
           .header('X-RateLimit-Limit', '100')
           .header('X-RateLimit-Remaining', '0')
           .header('X-RateLimit-Reset', Math.ceil(Date.now() / 1000) + 60)
           .json({
               error: 'RATE_LIMITED',
               message: 'Too many requests, please slow down',
               retryAfter: 60
           });
    }
}));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

// 500 Internal Server Error - Unexpected failures
// This should be your global error handler
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
    // Log full error for debugging (never expose to client)
    console.error('Unhandled error:', {
        message: err.message,
        stack: err.stack,
        requestId: req.id,
        path: req.path,
        method: req.method
    });
 
    // Return safe error to client
    res.status(500).json({
        error: 'INTERNAL_ERROR',
        message: 'An unexpected error occurred',
        requestId: req.id, // For support reference
        // NEVER include: err.message, err.stack, internal details
    });
});
 
 
// 502 Bad Gateway - Upstream service returned garbage
async function callPaymentService(data: PaymentRequest) {
    try {
        const response = await fetch('https://payments.internal/process', {
            method: 'POST',
            body: JSON.stringify(data)
        });
        
        if (!response.ok) {
            // Upstream returned error
            throw new UpstreamError(`Payment service returned ${response.status}`);
        }
        
        const result = await response.json();
        return result;
        
    } catch (error) {
        if (error instanceof UpstreamError) {
            throw {
                status: 502,
                body: {
                    error: 'BAD_GATEWAY',
                    message: 'Payment service returned an invalid response',
                    service: 'payments'
                }
            };
        }
        throw error;
    }
}
 
 
// 503 Service Unavailable - Intentional downtime or overload
app.use('/api', (req, res, next) => {
    if (maintenanceMode) {
        const maintenanceEnd = new Date('2025-01-08T02:00:00Z');
        const retryAfter = Math.ceil((maintenanceEnd.getTime() - Date.now()) / 1000);
        
        return res.status(503)
            .header('Retry-After', String(retryAfter))
            .json({
                error: 'SERVICE_UNAVAILABLE',
                message: 'Service is undergoing scheduled maintenance',
                estimatedEnd: maintenanceEnd.toISOString(),
                retryAfter: retryAfter
            });
    }
    
    // Circuit breaker: shed load when overwhelmed
    if (healthCheck.isOverloaded()) {
        return res.status(503)
            .header('Retry-After', '30')
            .json({
                error: 'SERVICE_UNAVAILABLE',
                message: 'Service is temporarily overloaded',
                retryAfter: 30
            });
    }
    
    next();
});
 
 
// 504 Gateway Timeout - Upstream didn't respond in time
async function fetchWithTimeout(url: string, timeoutMs: number) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), timeoutMs);
    
    try {
        const response = await fetch(url, { signal: controller.signal });
        return response;
    } catch (error) {
        if (error.name === 'AbortError') {
            throw {
                status: 504,
                body: {
                    error: 'GATEWAY_TIMEOUT',
                    message: 'Upstream service did not respond in time',
                    timeout: timeoutMs
                }
            };
        }
        throw error;
    } finally {
        clearTimeout(timeout);
    }
}
 
 
// 501 Not Implemented - We don't support this
app.all('/legacy-xml-api', (req, res) => {
    res.status(501).json({
        error: 'NOT_IMPLEMENTED',
        message: 'XML API is no longer supported',
        alternatives: ['/api/v2 (JSON)'],
        documentation: 'https://docs.example.com/migration'
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

// Standardized error response schema
interface APIError {
    // Always present
    error: string;              // Machine-readable error code
    message: string;            // Human-readable explanation
    
    // Optional but recommended
    requestId?: string;         // For support/debugging
    timestamp?: string;         // When the error occurred
    path?: string;              // What endpoint was called
    
    // Context-specific details
    details?: Record<string, any>;  // Additional information
    
    // For validation errors
    validationErrors?: Array<{
        field: string;
        message: string;
        code?: string;
        value?: any;
    }>;
    
    // For rate limiting
    retryAfter?: number;
    
    // For help
    documentation?: string;      // Link to relevant docs
    hint?: string;               // Suggestion for fixing
}
 
 
// Examples of well-structured error responses:
 
// 400 Bad Request - Malformed JSON
{
    "error": "INVALID_JSON",
    "message": "Request body contains invalid JSON",
    "requestId": "req_abc123def456",
    "details": {
        "position": 47,
        "issue": "Unexpected token at position 47"
    }
}
 
// 401 Unauthorized
{
    "error": "TOKEN_EXPIRED",
    "message": "Your authentication token has expired",
    "requestId": "req_abc123def456",
    "hint": "Obtain a new token via POST /auth/token",
    "documentation": "https://docs.example.com/auth"
}
 
// 403 Forbidden
{
    "error": "PERMISSION_DENIED",
    "message": "You do not have permission to delete this resource",
    "requestId": "req_abc123def456",
    "details": {
        "requiredRole": "admin",
        "yourRole": "user",
        "resource": "User",
        "action": "delete"
    }
}
 
// 404 Not Found
{
    "error": "RESOURCE_NOT_FOUND",
    "message": "User with ID 'usr_12345' not found",
    "requestId": "req_abc123def456",
    "details": {
        "resourceType": "User",
        "identifier": "usr_12345"
    }
}
 
// 422 Validation Error - Multiple field errors
{
    "error": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "requestId": "req_abc123def456",
    "validationErrors": [
        {
            "field": "email",
            "message": "Invalid email format",
            "code": "INVALID_FORMAT",
            "value": "not-an-email"
        },
        {
            "field": "age",
            "message": "Must be at least 18",
            "code": "MIN_VALUE",
            "value": 16
        },
        {
            "field": "password",
            "message": "Must contain at least one uppercase letter",
            "code": "WEAK_PASSWORD"
        }
    ]
}
 
// 429 Rate Limited
{
    "error": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your API rate limit",
    "requestId": "req_abc123def456",
    "retryAfter": 45,
    "details": {
        "limit": 100,
        "window": "1 minute",
        "remaining": 0,
        "resetAt": "2025-01-08T12:01:00Z"
    }
}
 
// 500 Internal Error (safe for client)
{
    "error": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-08T12:00:00Z",
    "support": "support@example.com"
}