Implementing Custom Error Codes in Swift 3: Best Practices and Patterns

Introduction

Error handling in Swift 3 and later versions has evolved significantly from Objective-C paradigms. While traditional NSError remains available, Swift introduces a more modern Error protocol system. Based on high-quality discussions from Stack Overflow, particularly the top-rated answer with a score of 10.0, this article systematically explains how to create and use custom error codes in Swift, with emphasis on network request applications.

Fundamentals of Swift Error Handling

Swift 3 elevates error handling to a core language feature through the Error protocol. Unlike Objective-C's NSError, Error is an empty protocol that allows developers to define any type as an error, establishing a foundation for type-safe and expressive error handling. In practice, common implementations include enums, structs, and classes, with enums being preferred due to their exhaustiveness and pattern-matching capabilities.

Error handling in network requests is particularly critical, requiring distinction between network-layer errors (e.g., connection failures), transport-layer errors (e.g., timeouts), and application-layer errors (e.g., HTTP status codes). The original question's code attempted to create an error object from an HTTP status code, but directly instantiating the Error protocol type is not permitted since Error lacks an initializer.

Designing Custom Error Types

Referencing the best answer, we can create a flexible error type system through protocol extension. First, define a base protocol inheriting from LocalizedError:

protocol OurErrorProtocol: LocalizedError {
    var title: String? { get }
    var code: Int { get }
}

The LocalizedError protocol extends Error, providing properties like errorDescription and failureReason to support localized error messages. By customizing this protocol, we unify error interfaces while maintaining flexibility in concrete implementations.

Based on this protocol, we can create a concrete error struct:

struct CustomError: OurErrorProtocol {
    var title: String?
    var code: Int
    var errorDescription: String? { return _description }
    var failureReason: String? { return _description }
    
    private var _description: String
    
    init(title: String?, description: String, code: Int) {
        self.title = title ?? "Error"
        self._description = description
        self.code = code
    }
}

This design encapsulates error code, title, and description while satisfying LocalizedError requirements through computed properties. The private _description property ensures immutability of the description string, aligning with value type safety principles.

Practical Network Request Error Handling

Applying custom error types to network requests, we can refactor the original code. First, define an HTTP error enum:

enum HTTPError: Error {
    case badRequest(description: String)
    case unauthorized(description: String)
    case notFound(description: String)
    case serverError(description: String)
    case custom(code: Int, description: String)
    
    var localizedDescription: String {
        switch self {
        case .badRequest(let desc): return "Bad Request: " + desc
        case .unauthorized(let desc): return "Unauthorized: " + desc
        case .notFound(let desc): return "Not Found: " + desc
        case .serverError(let desc): return "Server Error: " + desc
        case .custom(let code, let desc): return "Error " + String(code) + ": " + desc
        }
    }
    
    var statusCode: Int {
        switch self {
        case .badRequest: return 400
        case .unauthorized: return 401
        case .notFound: return 404
        case .serverError: return 500
        case .custom(let code, _): return code
        }
    }
}

Then, transform errors in the URLSession completion handler:

func handleResponse(data: Data?, response: URLResponse?, error: Error?) -> Result<Data, HTTPError> {
    if let error = error {
        return .failure(.custom(code: -1, description: error.localizedDescription))
    }
    
    guard let httpResponse = response as? HTTPURLResponse else {
        return .failure(.custom(code: -2, description: "Invalid response type"))
    }
    
    switch httpResponse.statusCode {
    case 200...299:
        guard let data = data else {
            return .failure(.custom(code: -3, description: "No data received"))
        }
        return .success(data)
    case 400:
        return .failure(.badRequest(description: extractErrorMessage(from: data)))
    case 401:
        return .failure(.unauthorized(description: extractErrorMessage(from: data)))
    case 404:
        return .failure(.notFound(description: extractErrorMessage(from: data)))
    case 500...599:
        return .failure(.serverError(description: extractErrorMessage(from: data)))
    default:
        return .failure(.custom(code: httpResponse.statusCode, 
                               description: extractErrorMessage(from: data)))
    }
}

private func extractErrorMessage(from data: Data?) -> String {
    guard let data = data,
          let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
          let message = json["message"] as? String else {
        return "Unknown error"
    }
    return message
}

This implementation uses Swift's Result type (Swift 5+), which clearly expresses success and failure outcomes. For Swift 3, custom enums or closure parameters can be used as alternatives.

Comparison with Alternative Approaches

Referencing other answers, we observe multiple error handling strategies:

1. Direct NSError Usage: As shown in answers 1 and 3, this is the most straightforward method but lacks type safety and Swift-native features. Example: let error = NSError(domain: "", code: 401, userInfo: [NSLocalizedDescriptionKey: "Invalid access token"]). While simple, it mixes Objective-C and Swift paradigms, hindering code consistency.
2. Simple Enums: As in answer 4, defining a finite error set via enums. This approach is concise and suitable for fixed error types but offers limited extensibility and difficulty in carrying additional information.
3. Hierarchical Error Systems: As in answer 5, organizing complex error classifications through nested enums. This method suits large applications but may introduce unnecessary complexity.

In contrast, protocol-based custom error types (best answer) balance flexibility, type safety, and expressiveness. They allow errors to carry rich contextual information while maintaining a unified interface, facilitating testing and maintenance.

Best Practice Recommendations

Based on the analysis, we propose the following best practices for Swift error handling:

• Prefer Swift-Native Error Types: Avoid direct NSError usage unless interfacing with Objective-C code.
• Leverage Enums for Finite Error Sets: Enums provide the clearest expression for known error cases.
• Unify Error Interfaces via Protocols: Define protocols to ensure consistency when multiple error types coexist.
• Implement LocalizedError for Localization: Provide user-friendly error messages through properties like errorDescription.
• Use Result Types for Asynchronous Operations: Swift 5+'s Result<Success, Failure> type is ideal for handling asynchronous errors.
• Maintain Rich but Concise Error Information: Errors should contain sufficient debugging information without exposing sensitive data.

Conclusion

Swift's error handling mechanisms offer powerful and flexible tools for developers. Through custom error types, we can create semantically rich, type-safe error systems that significantly enhance code quality and maintainability. In asynchronous operations like network requests, combining protocols, enums, and modern Swift features enables robust error handling workflows. The methods discussed here not only address the technical challenges in the original question but also provide a systematic solution for Swift error handling.

In practice, choose an appropriate error handling strategy based on application scale and requirements. For simple apps, direct enums may suffice; for complex systems, protocol-based custom types offer better extensibility. Regardless of the approach, adhering to Swift's design philosophy and type safety principles is key.