Error Response Design

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

{
  // WHAT HAPPENED: Machine-readable error identifier
  "code": "PAYMENT_DECLINED",
  
  // WHY IT HAPPENED: Human-readable explanation
  "message": "The payment method was declined by the card issuer",
  
  // ADDITIONAL CONTEXT: Structured details
  "details": {
    "reason": "insufficient_funds",
    "declineCode": "51",
    "cardBrand": "visa",
    "lastFourDigits": "4242"
  },
  
  // WHERE IT HAPPENED: Trace information
  "requestId": "req_a1b2c3d4e5f6",
  "timestamp": "2024-01-15T14:30:00.000Z",
  
  // WHAT CAN I DO ABOUT IT: Actionable guidance
  "recoveryOptions": {
    "retryable": false,
    "suggestedActions": [
      "Try a different payment method",
      "Contact your card issuer for details"
    ],
    "helpUrl": "https://docs.example.com/errors/payment-declined"
  },
  
  // MACHINE-READABLE CATEGORIZATION
  "type": "client_error",
  "category": "payment"
}

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

// GOOD: Hierarchical, descriptive, stable error codes
enum ErrorCode {
    // Authentication domain
    AUTH_TOKEN_EXPIRED = "AUTH.TOKEN_EXPIRED",
    AUTH_TOKEN_INVALID = "AUTH.TOKEN_INVALID",
    AUTH_TOKEN_MISSING = "AUTH.TOKEN_MISSING",
    AUTH_INSUFFICIENT_PERMISSIONS = "AUTH.INSUFFICIENT_PERMISSIONS",
    
    // User domain
    USER_NOT_FOUND = "USER.NOT_FOUND",
    USER_ALREADY_EXISTS = "USER.ALREADY_EXISTS",
    USER_EMAIL_NOT_VERIFIED = "USER.EMAIL_NOT_VERIFIED",
    USER_ACCOUNT_SUSPENDED = "USER.ACCOUNT_SUSPENDED",
    
    // Validation domain
    VALIDATION_FIELD_REQUIRED = "VALIDATION.FIELD_REQUIRED",
    VALIDATION_FIELD_INVALID = "VALIDATION.FIELD_INVALID",
    VALIDATION_FIELD_TOO_LONG = "VALIDATION.FIELD_TOO_LONG",
    VALIDATION_FIELD_FORMAT = "VALIDATION.FIELD_FORMAT",
    
    // Payment domain
    PAYMENT_DECLINED = "PAYMENT.DECLINED",
    PAYMENT_EXPIRED_CARD = "PAYMENT.EXPIRED_CARD",
    PAYMENT_INSUFFICIENT_FUNDS = "PAYMENT.INSUFFICIENT_FUNDS",
    PAYMENT_FRAUD_DETECTED = "PAYMENT.FRAUD_DETECTED",
    
    // Rate limiting domain
    RATE_LIMIT_EXCEEDED = "RATE_LIMIT.EXCEEDED",
    RATE_LIMIT_QUOTA_EXHAUSTED = "RATE_LIMIT.QUOTA_EXHAUSTED",
    
    // Generic
    INTERNAL_ERROR = "INTERNAL.ERROR",
    SERVICE_UNAVAILABLE = "SERVICE.UNAVAILABLE",
}
 
// BAD: Vague, unstable, or confusing error codes
enum BadErrorCodes {
    // Too vague—what kind of error?
    ERROR = "ERROR",
    FAILED = "FAILED",
    INVALID = "INVALID",
    
    // Exposes implementation details
    SQL_EXCEPTION = "SQL_EXCEPTION",
    NULL_POINTER = "NULL_POINTER",
    
    // Numeric codes lose meaning
    E001 = "E001",
    E002 = "E002",
    
    // Inconsistent formatting
    UserNotFound = "UserNotFound",
    payment_failed = "payment_failed",
    CARD_ERROR = "CARD_ERROR",
}

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

// Message templates with dynamic details
const errorMessages = {
    // Include the problematic value
    VALIDATION_FIELD_REQUIRED: (field: string) =>
        `The ${field} field is required`,
    
    // Show what was received vs expected
    VALIDATION_FIELD_FORMAT: (field: string, received: string, expected: string) =>
        `Invalid ${field} format: '${received}' does not match expected pattern '${expected}'`,
    
    // Include limits
    VALIDATION_FIELD_TOO_LONG: (field: string, max: number, actual: number) =>
        `${field} exceeds maximum length of ${max} characters (received ${actual})`,
    
    // Time-based info
    AUTH_TOKEN_EXPIRED: (expiredAt: Date) =>
        `Your session expired at ${formatDate(expiredAt)}. Please sign in again.`,
    
    // Retry guidance
    RATE_LIMIT_EXCEEDED: (retryAfter: number) =>
        `Rate limit exceeded. Please wait ${retryAfter} seconds before retrying.`,
    
    // User-friendly payment messages
    PAYMENT_INSUFFICIENT_FUNDS: (cardLast4: string) =>
        `The card ending in ${cardLast4} was declined due to insufficient funds. Please use a different card or add funds.`,
} as const;
 
// Usage
throw new ApiError({
    code: ErrorCode.VALIDATION_FIELD_TOO_LONG,
    message: errorMessages.VALIDATION_FIELD_TOO_LONG('description', 500, 1247),
    details: { field: 'description', maxLength: 500, actualLength: 1247 }
});

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

// Validation errors: per-field details
{
  "code": "VALIDATION.MULTIPLE_ERRORS",
  "message": "Request validation failed",
  "details": {
    "errors": [
      {
        "field": "email",
        "code": "VALIDATION.FIELD_FORMAT",
        "message": "Invalid email format",
        "value": "not-an-email",
        "constraint": "^[\\w.-]+@[\\w.-]+\\.\\w+$"
      },
      {
        "field": "age",
        "code": "VALIDATION.FIELD_RANGE",
        "message": "Age must be between 18 and 120",
        "value": 15,
        "constraint": { "min": 18, "max": 120 }
      },
      {
        "field": "items[2].quantity",
        "code": "VALIDATION.FIELD_REQUIRED",
        "message": "Quantity is required",
        "value": null,
        "path": ["items", 2, "quantity"]
      }
    ]
  }
}

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

// Map error codes to HTTP status codes
const errorCodeToHttpStatus: Record<string, number> = {
    // Authentication: 401
    'AUTH.TOKEN_EXPIRED': 401,
    'AUTH.TOKEN_INVALID': 401,
    'AUTH.TOKEN_MISSING': 401,
    
    // Authorization: 403
    'AUTH.INSUFFICIENT_PERMISSIONS': 403,
    'AUTH.ACCOUNT_SUSPENDED': 403,
    
    // Not found: 404
    'USER.NOT_FOUND': 404,
    'ORDER.NOT_FOUND': 404,
    'RESOURCE.NOT_FOUND': 404,
    
    // Conflicts: 409
    'USER.ALREADY_EXISTS': 409,
    'ORDER.ALREADY_PROCESSED': 409,
    'CONCURRENT_MODIFICATION': 409,
    
    // Validation: 422 (or 400)
    'VALIDATION.FIELD_REQUIRED': 422,
    'VALIDATION.FIELD_INVALID': 422,
    'VALIDATION.BUSINESS_RULE': 422,
    
    // Rate limiting: 429
    'RATE_LIMIT.EXCEEDED': 429,
    'RATE_LIMIT.QUOTA_EXHAUSTED': 429,
    
    // Server errors: 5xx
    'INTERNAL.ERROR': 500,
    'SERVICE.DEPENDENCY_FAILED': 502,
    'SERVICE.UNAVAILABLE': 503,
    'SERVICE.TIMEOUT': 504,
};
 
// Unified error handler
function toHttpResponse(error: ApiError): HttpResponse {
    const statusCode = errorCodeToHttpStatus[error.code] ?? 500;
    
    return {
        status: statusCode,
        body: {
            code: error.code,
            message: error.message,
            details: error.details,
            requestId: getCurrentRequestId(),
            timestamp: new Date().toISOString(),
        },
        headers: buildErrorHeaders(error, statusCode),
    };
}
 
function buildErrorHeaders(error: ApiError, status: number): Record<string, string> {
    const headers: Record<string, string> = {};
    
    if (status === 429 && error.details?.retryAfter) {
        headers['Retry-After'] = String(error.details.retryAfter);
    }
    
    if (status === 401) {
        headers['WWW-Authenticate'] = 'Bearer realm="api"';
    }
    
    return headers;
}

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

// User enumeration protection
// BAD: Different errors reveal user existence
app.post('/login', (req, res) => {
    const user = findUser(req.body.email);
    if (!user) {
        return res.status(404).json({ 
            error: "User not found"  // Reveals email not registered
        });
    }
    if (!verifyPassword(user, req.body.password)) {
        return res.status(401).json({ 
            error: "Invalid password"  // Confirms email exists
        });
    }
    // ... login success
});
 
// GOOD: Same error for both cases
app.post('/login', (req, res) => {
    const user = findUser(req.body.email);
    const valid = user && verifyPassword(user, req.body.password);
    
    if (!valid) {
        return res.status(401).json({
            code: "AUTH.INVALID_CREDENTIALS",
            message: "Invalid email or password"  // No clue which is wrong
        });
    }
    // ... login success
});
 
// Internal error sanitization
function toErrorResponse(error: Error, requestId: string): ApiError {
    // Log full details internally
    logger.error('Request failed', {
        requestId,
        error: error.message,
        stack: error.stack,
        cause: error.cause,
    });
    
    // Return sanitized response
    if (error instanceof ApiError) {
        return error;  // Already sanitized
    }
    
    // Unknown errors get generic response
    return {
        code: 'INTERNAL.ERROR',
        message: 'An unexpected error occurred',
        requestId,
        // NO stack trace, NO internal details
    };
}