DEV Community: Pavel Andreev

How to Build a Robust Network Layer in Swift via Clean Architecture 🚀 Let’s be honest: writing a network layer in iOS can get messy really fast. https://dev.to/pavel_andreev_ios/robust-network-layer-in-swift-via-clean-architecture-approach-42h8

Pavel Andreev — Mon, 16 Mar 2026 05:20:50 +0000

Robust Network Layer in Swift via Clean Architecture Approach

Pavel Andreev ・ Feb 17

#swift #swiftprogramming #ios #architecture

The article show how build good extendable app using by Clean Architecture Approach

Pavel Andreev — Tue, 17 Feb 2026 14:24:08 +0000

Robust Network Layer in Swift via Clean Architecture Approach

Pavel Andreev ・ Feb 17

#swift #swiftprogramming #ios #architecture

Robust Network Layer in Swift via Clean Architecture Approach

Pavel Andreev — Tue, 17 Feb 2026 14:22:53 +0000

Networking is the backbone of almost every modern iOS application. However, as projects grow in complexity, the network layer often becomes a “junk drawer” for URL construction, messy completion handlers, and scattered error logic. This tight coupling makes unit testing difficult and maintenance a nightmare.

In this article, we are going to build a reusable, testable, and type-safe Network Layer from scratch. By leveraging Clean Architecture principles, the power of Swift Generics, and the modern elegance of Async/Await, we will create a solution that separates concerns and scales with your app.

Whether you are preparing for a technical interview or refactoring a production codebase, this approach provides a solid foundation for any Swift project.

1. Centralizing API Endpoints with Type-Safe Enums

One of the first steps in decoupling your network logic is to move away from hardcoded strings scattered throughout your ViewModels or Repositories. Instead, we use a Type-Safe Enum to define our API contract.

/// Defines the available API endpoints in the application.
/// This acts as a centralized source of truth for all URL construction.
enum APIEndPoint {
    case list
    case detail(id: String)

    /// Computed property to generate the full URL for each endpoint.
    /// In a production environment, you might use URLComponents for safer query parameter handling.
    var url: URL {
        switch self {
        case .list:
            // Endpoint for fetching the list of desserts
            return URL(string: "https://themealdb.com/api/json/v1/1/filter.php?c=Dessert")!
        case .detail(id: let id):
            // Endpoint for fetching specific meal details by ID
            return URL(string: "https://themealdb.com/api/json/v1/1/lookup.php?i=\(id)")!
        }
    }
}

2. Moving Beyond Generic Failures

In a production-ready network layer, simply knowing that “an error occurred” is rarely enough. To provide a great user experience and simplify debugging, we need to categorize failures. The ServiceErrors enum allows us to transform raw HTTP responses into meaningful, domain-specific types.

/// Custom error types to categorize network and server-side failures.
/// This allows the UI or Domain layer to provide specific feedback to the user.
enum ServiceErrors: Error {
    case internalError(_ statusCode: Int) // Errors related to client-side or logic issues (4xx)
    case serverError(_ statusCode: Int)   // Errors related to server-side issues (5xx)
}

3. Abstraction through Protocols

In Clean Architecture, we aim for the Dependency Inversion Principle: High-level modules (like ViewModels or Use Cases) should not depend on low-level modules (like a concrete NetworkManager). Instead, both should depend on abstractions.

This is where the NetworkProtocol comes in. It acts as the "contract" for our networking layer.

/// The blueprint for our Network Layer. 
/// Using a protocol allows us to mock the network for Unit Testing (Dependency Inversion).
protocol NetworkProtocol {
    /// Generic fetch method using a raw URL.
    func fetch<T>(_ url: URL) async throws -> T where T : Decodable

    /// Generic fetch method using the APIEndPoint abstraction.
    func fetch<T>(_ endPoint: APIEndPoint) async throws -> T where T : Decodable
}

extension NetworkProtocol {
    /// Default implementation to bridge the Endpoint enum with the raw URL fetcher.
    func fetch<T>(_ endPoint: APIEndPoint) async throws -> T where T : Decodable {
        try await fetch(endPoint.url)
    }
}

Power of Generics and Type-Safety
The use of where T: Decodable makes our network layer incredibly flexible. Instead of writing a separate fetch method for every single model (e.g., fetchDesserts, fetchDetails), we write one generic method. As long as your data model conforms to Decodable, this protocol can handle it, ensuring type safety throughout the entire app.

Modern Concurrency with async/await
By defining our methods as async throws, we embrace the modern Swift concurrency model. This provides several benefits over traditional completion handlers:

Readability: The code reads linearly, making it much easier to follow.
Safety: It eliminates common bugs associated with forgetting to call a completion block or accidentally calling it twice.
Error Propagation: Errors are thrown naturally, allowing the caller to use do-catch blocks for clean error handling.
Protocol Extensions: Adding Convenience
The protocol extension provides a default implementation for fetching via our APIEndPoint enum. This is a powerful pattern because:

DRY (Don’t Repeat Yourself): We only have to implement the raw URL logic once in the concrete class.
Separation of Concerns: The protocol extension handles the transformation from an abstraction (APIEndPoint) to a concrete requirement (URL), keeping our main NetworkManager implementation clean and focused purely on the network request.

4. The Engine: Implementing the NetworkManager

Now that we have defined our endpoints, errors, and blueprint, it’s time to build the concrete implementation: the NetworkManager. This class is responsible for the "heavy lifting"—communicating with the internet and transforming raw bytes into Swift objects.

/// The concrete implementation of the NetworkProtocol.
/// This class handles the actual data task and JSON decoding.
final class NetworkManager: NetworkProtocol {

    private let urlSession: URLSession
    private let decoder = JSONDecoder()

    /// Initializer with Dependency Injection.
    /// By injecting URLSession, we can easily swap it with a MockSession during testing.
    init(urlSession: URLSession = .shared) {
        self.urlSession = urlSession
    }

    /// Fetches data from a given URL, validates the HTTP response, and decodes the JSON.
    /// - Parameter url: The destination URL.
    /// - Returns: A decoded object of type T.
    func fetch<T>(_ url: URL) async throws -> T where T : Decodable {
        // Perform the network request using Swift Concurrency (async/await)
        let (data, response) = try await urlSession.data(from: url)

        // Ensure the response is an HTTPURLResponse and the status code is within the 200-299 range.
        guard let httpResponse = response as? HTTPURLResponse,
              200..<300 ~= httpResponse.statusCode else {

            // Cast to HTTPURLResponse to extract the status code for error handling.
            let statusCode = (response as? HTTPURLResponse)?.statusCode ?? 0

            switch statusCode {
            case 400...499:
                throw ServiceErrors.internalError(statusCode)
            default:
                throw ServiceErrors.serverError(statusCode)
            }
        }

        // Decode the data into the requested generic type.
        // Throws an error if the JSON mapping fails.
        let result = try decoder.decode(T.self, from: data)
        return result
    }
}

Why a final class?
We mark the NetworkManager as final to prevent subclassing. In a Clean Architecture setup, this class should be a specialized tool that does one thing well. Disabling inheritance improves compilation time and ensures the internal logic remains protected and immutable.

Dependency Injection for Testability
The initializer takes a URLSession as a parameter, defaulting to .shared. This is a crucial detail for Unit Testing.

In production, the app uses the standard shared session.
In tests, you can inject a URLSession with a mocked configuration to return local data without ever hitting a real server. This keeps your tests fast, reliable, and offline-capable.
The Modern Request Lifecycle
The fetch method implementation demonstrates the elegance of Swift Concurrency:

Data Fetching: We use urlSession.data(from: url), which suspends the function without blocking the main thread.
Validation: Before we even look at the data, we validate the HTTPURLResponse. We use the pattern matching operator (200..<300 ~= statusCode) to ensure the request was successful.
Detailed Error Mapping: If the request fails, we switch through the status code. This allows us to throw our custom ServiceErrors, providing clear context to the upper layers of the architecture (like the ViewModel).
Decoding: Finally, we use JSONDecoder to map the raw data into our generic type T. Because we used Generics, this single line of code can handle a User model, a List of meals, or a Product detail model.
Separation of Concerns
Notice that NetworkManager doesn't know what data it is fetching; it only knows how to fetch and decode it. By keeping the decoding logic here, we ensure that the rest of the app only ever deals with clean, strongly-typed Swift models, never raw JSON.

5.Bridging Data and Business Logic

While the NetworkManager handles the technicalities of HTTP and JSON, we need a specialized object to handle the Domain Logic. This is where MealManager comes in. It serves as a Repository that provides the rest of the application with clean, high-level methods to access data.

final class MealManager {

    private let networkManager: NetworkProtocol

    init(networkManager: NetworkProtocol) {
        self.networkManager = networkManager
    }

    // Fetches a list of meals from a network source.
    func fetchMeals() async throws -> [Meal] {
        // The response is expected to conform to MealsResponse<[Meal]>, a generic type expecting an array of Meal.
        let response: MealsResponse<[Meal]> = try await networkManager.fetch(.list)
        return response.meals
    }

    // Fetch meal detail
    func fetchMealDetail(id: Meal.ID) async throws -> MealDetail? {
        // The response is expected to conform to MealsResponse<[MealDetail]>, which is a generic type expecting an array of MealDetail.
        let response: MealsResponse<[MealDetail]> = try await networkManager.fetch(.detail(id: id))
        return response.meals.first
    }
}

Real-World Dependency Inversion
Notice that MealManager does not know NetworkManager exists. Instead, it only knows about NetworkProtocol.

The Benefit: If you ever decide to replace URLSession with another framework (like Alamofire) or a local database (like Core Data), you only need to create a new class conforming to NetworkProtocol. You won't have to change a single line of code inside MealManager.
Simplifying the Data Flow
APIs often wrap their data in “envelope” objects (like your MealsResponse). The UI layer doesn't care about these wrappers; it only wants the list of meals. MealManager handles this "unwrapping" logic:

In fetchMeals(), it converts the network response into a clean [Meal] array.
In fetchMealDetail(), it handles the logic of extracting the first item from a detail array, returning an optional MealDetail?.
This ensures that your ViewModels stay lean. They don’t have to deal with indexing arrays or decoding envelopes — they just ask the manager for the data they need.

6. Connecting Logic to the UI

The MainViewModel acts as the conductor of our data flow. It takes the information provided by the MealManager and prepares it for the SwiftUI views to display.

protocol GetMealsProtocol {
    func fetchMeals() async
}

@MainActor
class MainViewModel: ObservableObject, GetMealsProtocol {

    @Published var meals: [Meal] = []

    private let manager: MealManager
    private var errorMessage: String = ""

    init(manager: MealManager) {
        self.manager = manager
    }

    func fetchMeals() async {
        do {
            let meals = try await manager.fetchMeals()
            try Task.checkCancellation()
            self.meals = meals
        } catch {
            self.errorMessage = error.localizedDescription
        }
    }
}

Why Use a Protocol for the ViewModel?
You might notice the GetMealsProtocol. While many developers skip this step, abstracting your ViewModel behind a protocol is a hallmark of Clean Architecture. It allows you to:

Mock the View State: You can create a “MockViewModel” that returns hardcoded data to preview your SwiftUI views in different states (loading, success, error) without running the full app logic.
Decouple the View: The SwiftUI View doesn’t need to know about the concrete class; it only needs an object that can “fetch meals.”
Thread Safety with @MainActor
In the world of async/await, it is easy to accidentally update the UI from a background thread. By marking the class with @MainActor, we guarantee that all updates to our @Published properties (like meals) happen on the Main Thread. This eliminates common crashes and "purple warnings" in Xcode related to threading.

Robust Task Management
The fetchMeals method demonstrates a production-standard way to handle asynchronous tasks:

Do-Catch Block: We gracefully handle any errors thrown by the network layer. Instead of the app crashing, we capture the error to show a user-friendly message.
Task Cancellation: The line try Task.checkCancellation() is a professional touch. In SwiftUI, if a user navigates away from a screen before the network request finishes, the task is cancelled. Checking for cancellation ensures we don't spend CPU cycles processing data for a screen that is no longer visible.
State Management: Once the data is successfully fetched, we update the meals property. Because it is marked as @Published, SwiftUI will automatically re-render the UI to show the new list.
Conclusion: Scaling with Confidence
Building a network layer isn’t just about making an API call; it’s about creating a foundation that your entire team can trust. By moving away from “stringly-typed” URLs and messy completion handlers, we’ve built a system that is resilient to change.

Through the lens of Clean Architecture, we achieved several key goals:

Separation of Concerns: Our NetworkManager handles the "how," our MealManager handles the "what," and our ViewModel handles the "when."
Testability: By depending on protocols rather than concrete classes, we can swap real network calls for mocks in seconds, making our unit tests fast and reliable.
Safety: Using async/await and @MainActor ensures that our code is modern, readable, and thread-safe by design.
The beauty of this architecture is its flexibility. Whether you are adding new features, implementing an offline cache, or migrating to a new API version, your codebase is now prepared to handle it with minimal friction.

Explore the Full Source Code
Architecture is best understood by seeing how all the moving parts work together in a real environment. I have prepared a complete, production-ready example on GitHub. You can explore the implementation of the protocols, the generic response handling, and the SwiftUI integration here

I hope this guide helps you build more robust and maintainable iOS applications. If you found this helpful, feel free to leave a clap or a comment with your thoughts on how you handle networking in your own projects!

My Linkedin

Swift: Master of Decoding messy json

Pavel Andreev — Tue, 17 Feb 2026 07:26:40 +0000

I recently came across an interesting challenge involving JSON decoding in Swift. Like many developers, when faced with a large, complex JSON response, my first instinct was to reach for “quick fix” tools. I wanted to see how our popular online resources — like Quicktype, various JSON-to-Swift converters, and even modern AI models — would handle a messy, repetitive data structure.

To be honest, I was completely underwhelmed.

The Problem: The “Flat” JSON Nightmare

The issue arises when you encounter a legacy API or a poorly structured response that uses “flat” numbered properties instead of clean arrays. Take a look at this JSON sample:

{
  "meals": [
    {
      "idMeal": "52771",
      "strMeal": "Spicy Arrabiata Penne",
      "strInstructions": "Bring a large pot of water to a boil...",
      "strMealThumb": "https://www.themealdb.com/images/media/meals/ustsqw1468250014.jpg",
      "strIngredient1": "penne rigate",
      "strIngredient2": "olive oil",
      "strIngredient3": "garlic",
      "strIngredient4": "chopped tomatoes",
      "strIngredient5": "red chilli flakes",
      // ... this continues up to strIngredient20
      "strMeasure1": "1 pound",
      "strMeasure2": "1/4 cup",
      "strMeasure3": "3 cloves",
      // ... this continues up to strMeasure20
    }
  ]
}

Why Online Converters Fail

When I plugged this into standard conversion tools, the result was a maintenance nightmare. They generated a “wall of properties” that looked something like this:

struct Meal: Codable {
    let idMeal: String
    let strMeal: String
    let strInstructions: String?
    let strMealThumb: String?

    // The repetitive property nightmare
    let strIngredient1: String?
    let strIngredient2: String?
    let strIngredient3: String?
    // ...
    let strIngredient20: String?

    let strMeasure1: String?
    let strMeasure2: String?
    let strMeasure3: String?
    // ...
    let strMeasure20: String?
}

Let’s be honest the code generated by those online tools belongs in the “trash bin” for any serious project. Not only is it unscalable, but imagine the look on your senior developer’s face during a PR review when they see 40+ optional properties. It’s a maintenance nightmare and a blow to your professional reputation.

I decided to take control of the decoding process to make it clean, Swifty, and — most importantly — production-ready. Here is how I structured the solution and why it works.

The Secret Weapon: Why We Use a Struct for CodingKeys
In 99% of Swift tutorials, you see CodingKeys defined as an enum. Enums are great when you know every single key at compile time. But in our case, we have a "flat" JSON with keys like strIngredient1, strIngredient2... up to 20.

Writing an enum with 40 cases is not just boring — it’s bad engineering. That is why we use a struct instead.

1. Breaking the Protocol Requirements

To conform to CodingKey, a type must handle both String and Int values. By using a struct, we can pass any string into the initializer at runtime.

struct CodingKeys: CodingKey {
    let stringValue: String
    var intValue: Int?

    init?(stringValue: String) {
        self.stringValue = stringValue
    }

    // This allows us to map any raw string from the JSON to our logic
    init(rawValue: String) {
        self.stringValue = rawValue
    }

    init?(intValue: Int) { return nil } // We don't need integer keys here
}

2. Mapping “Ugly” Keys to Clean Names

You don’t have to stick with the API’s naming conventions inside your app. Notice how I used static var to create aliases. This keeps the rest of the decoding logic readable while keeping the "dirty" API keys isolated inside this struct.

static var name = CodingKeys(rawValue: "strMeal")
static var thumb = CodingKeys(rawValue: "strMealThumb")
static var instructions = CodingKeys(rawValue: "strInstructions")

3. The Power of Dynamic Key Generation

This is the part that makes this approach superior to any AI-generated code. We created static functions that use string interpolation to generate keys on the fly.

static func strIngredient(_ index: Int) -> Self {
    CodingKeys(rawValue: "strIngredient\(index)")
}

static func strMeasure(_ index: Int) -> Self {
    CodingKeys(rawValue: "strMeasure\(index)")
}

Instead of hardcoding strIngredient1, strIngredient2, etc., we now have a "key factory." When we loop through 1...20 in our initializer, we simply call these functions. It’s clean, it’s reusable, and it’s significantly harder to make a typo than writing 40 individual cases.

4. Building a Model That Actually Makes Sense

The original JSON treats an ingredient and its measurement as two strangers living in different houses. In our app, they are a couple. By nesting a dedicated struct, we fix the data architecture at the source:

struct Ingredient: Decodable, Hashable {
    let id: Int
    let name: String
    let measure: String
}

Why Hashable and the id?

I added an id property using the loop index. Why? Because modern SwiftUI views like List and ForEach require identifiable data. By conforming to Hashable, we ensure:

No UI Glitches: SwiftUI won’t get confused if two different ingredients have the same name (like two different types of “Salt”).
Performance: Diffable data sources love hashable objects.

5. Cleaning Up the “API Smell”

Before we get to the initializer, look at how we define our main properties. We aren’t just copying what the API gives us; we are translating it into Clean Swift.

let name: String
let thumb: URL?
let instructions: String
let ingredients: [Ingredient]

Goodbye str Prefix: We dropped the Hungarian notation. name is better than strMeal.
Proper Types: We decode the thumbnail directly into a URL?. If the API sends a broken link or an empty string, our decoder handles it gracefully during the parsing phase, not later in the View.

6. The Smart Initializer: Our “Data Bouncer”

This is the finale. Instead of blindly accepting every key the JSON offers, our custom init(from:) acts like a bouncer at a club—only valid data gets in.

init(from decoder: any Decoder) throws {
    let container = try decoder.container(keyedBy: CodingKeys.self)

    // 1. Decode simple properties using our clean aliases
    self.name = try container.decode(String.self, forKey: .name)
    self.thumb = try? container.decode(URL.self, forKey: .thumb)
    self.instructions = try container.decode(String.self, forKey: .instructions)

    // 2. The Dynamic Decoding Loop
    var ingredients: [Ingredient] = []

    for index in 1...20 {
        // We use 'try?' because some keys might be null or missing
        if let name = try? container.decode(String.self, forKey: .strIngredient(index)),
           let measure = try? container.decode(String.self, forKey: .strMeasure(index)),
           !name.isEmpty, !measure.isEmpty 
        {
            // We only save it if the name AND measure are valid and non-empty
            ingredients.append(Ingredient(id: index, name: name, measure: measure))
        }
    }
    self.ingredients = ingredients
}

The Final Result: Clean, Swifty, and UI-Ready

After all that work behind the scenes, look at what we’ve achieved. We have transformed a “flat” JSON nightmare into a model that is a joy to use. This is what the rest of your app sees now:

struct MealDetail {
    let name: String
    let instructions: String
    let thumb: URL?
    let ingredients: [Ingredient] 
}

Pure Simplicity in the UI

Because we did the heavy lifting during the decoding phase — filtering empty values and grouping ingredients — our SwiftUI code becomes incredibly clean. We don’t need any complex logic in the View; we just map the data directly to the components.

The Cherry on Top: Making Mocking Easy

You might have noticed one small side effect: when we define a custom init(from: Decoder), Swift stops generating the default memberwise initializer. This can make writing unit tests or SwiftUI Previews a bit annoying.

To fix this and keep our codebase “test-friendly,” we can add this simple extension. This allows us to create “Mock” data for our UI without needing a JSON file.

extension MealDetail {
    // Restoring the ability to create manual instances for Mocks and Tests
    init(name: String, thumb: URL?, instructions: String, ingredients: [Ingredient]) {
        self.name = name
        self.thumb = thumb
        self.instructions = instructions
        self.ingredients = ingredients
    }
}

Now, creating a preview is as simple as: let mock = MealDetail(name: "Pasta", thumb: nil, instructions: "Cook it.", ingredients: [])

Conclusion

The next time you’re faced with a messy API, remember: don’t let the backend dictate your frontend architecture. Online tools and AI might give you a quick “copy-paste” solution, but they often lead to technical debt. By taking control of your Decodable implementation, you create code that is:

Readable: Clear, intent-based property names.
Robust: Filters out empty or corrupt data at the source.
Maintainable: Easy to test and easy to display in the UI.

Happy coding, and keep your models clean!

full code is here

Swift: The Complete Guide to Error Handling in the Network Layer

Pavel Andreev — Thu, 12 Feb 2026 19:29:03 +0000

In my previous article, we explored how to construct a robust, abstract network layer using Clean Architecture. The response was fantastic, but I received a recurring piece of feedback: the error handling was a bit too thin for a real-world production environment.

Categorizing HTTP Status Codes

To provide a more granular and descriptive way of handling network events, I decided to categorize HTTP status codes into specific enums. This approach ensures that our logic is both type-safe and highly readable. By referencing the MDN Web Docs, I mapped out each response category to its own structure.

This categorization allows us to handle informational updates, successful transfers, and various error types with specialized logic rather than a giant, messy switch statement.

The Unified Interface: HTTPResponseDescription

Before diving into the specific error groups, we need a “blueprint.” The HTTPResponseDescription protocol ensures that every response type in our system, regardless of its origin, exposes two critical pieces of information: the numeric status code and a human-readable description.

This is the “secret sauce” that allows our UI layer to display meaningful messages to the user without needing to know the technical details of the error.

protocol HTTPResponseDescription {
    var statusCode: Int { get }
    var description: String { get }
}

Handling System-Level Failures: NSURLErrorCode

While HTTP status codes (like 404 or 500) tell us what the server thinks, sometimes the request doesn’t even reach the server. This happens when the URL is malformed, the connection times out, or the internet is simply gone.

To handle these “pre-response” failures, I created the NSURLErrorCode enum. By conforming it to our HTTPResponseDescription protocol, we can handle these low-level network issues using the exact same pattern as our HTTP responses.

enum NSURLErrorCode: Error, HTTPResponseDescription {

    case unknown
    case invalidResponse
    case badURL
    case timedOut
    case decodingError
    case outOfRange(Int)

    init(code: Int) {
        switch code {
        case 0: self = .unknown
        case 1: self = .invalidResponse
        case 2: self = .badURL
        case 3: self = .timedOut
        default:  self = .outOfRange(code)
        }
    }

    var statusCode: Int {
        switch self {
        case .unknown: return 0
        case .invalidResponse: return 1
        case .badURL: return 2
        case .timedOut: return 3
        case .decodingError: return 4
        case .outOfRange(let code): return code
        }
    }

    var description: String {
        switch self {
        case .badURL: return "The URL was malformed."
        case .invalidResponse: return "Invalid response"
        case .decodingError: return "Failed to decode the response."
        case .outOfRange(let statusCode): return "The request \(statusCode) was out of range."
        case .unknown: return "An unknown error occurred."
        case .timedOut: return "The request timed out."

        }
    }
}

1xx: Informational Responses

The first group represents Informational Responses, which indicate that the request was received and the process is continuing.

/// 1..x
enum InformationalResponse: Error, HTTPResponseDescription {
    case continueResponse
    case switchingProtocols
    case processingDeprecated
    case earlyHints
    case unknown(Int)

    init(code: Int) {
        switch code {
        case 100: self = .continueResponse
        case 101: self = .switchingProtocols
        case 102: self = .processingDeprecated
        case 103: self = .earlyHints
        default:  self = .unknown(code)
        }
    }

    var statusCode: Int {
        switch self {
        case .continueResponse:     return 100
        case .switchingProtocols:   return 101
        case .processingDeprecated: return 102
        case .earlyHints:           return 103
        case .unknown(let code):    return code
        }
    }

    var description: String {
        switch self {
        case .continueResponse:     return "Continue"
        case .switchingProtocols:   return "Switching Protocols"
        case .processingDeprecated: return "Processing"
        case .earlyHints:           return "Early Hints"
        case .unknown(let code):    return "Unknown code: \(code)"
        }
    }

}

2xx: Successful Responses

While we often focus on handling errors, understanding the nuances of success is equally important for a high-quality network layer. The 2xx category indicates that the client’s request was successfully received, understood, and accepted.

While a simple 200 OK is the most common response, other codes like 201 Created (essential for POST requests) or 204 No Content (common for DELETE operations) provide critical context to your business logic. By explicitly mapping these, we can trigger specific UI updates—like navigating back after a successful creation—with absolute certainty.

/// 2xx Success: The action was successfully received, understood, and accepted.
enum SuccessfulResponses: Error, Equatable, HTTPResponseDescription {
    case ok
    case created
    case accepted
    case nonAuthoritativeInformation
    case noContent
    case resetContent
    case partialContent
    case multiStatus
    case alreadyReported
    case imUsed
    case unknown(Int)

    init(code: Int) {
        switch code {
        case 200: self = .ok
        case 201: self = .created
        case 202: self = .accepted
        case 203: self = .nonAuthoritativeInformation
        case 204: self = .noContent
        case 205: self = .resetContent
        case 206: self = .partialContent
        case 207: self = .multiStatus
        case 208: self = .alreadyReported
        case 226: self = .imUsed
        default:  self = .unknown(code)
        }
    }

    var statusCode: Int {
        switch self {
        case .ok:                           return 200
        case .created:                      return 201
        case .accepted:                     return 202
        case .nonAuthoritativeInformation:  return 203
        case .noContent:                    return 204
        case .resetContent:                 return 205
        case .partialContent:               return 206
        case .multiStatus:                  return 207
        case .alreadyReported:              return 208
        case .imUsed:                       return 226
        case .unknown(let code):            return code
        }
    }

    var description: String {
        switch self {
        case .ok:                           return "OK"
        case .created:                      return "Created"
        case .accepted:                     return "Accepted"
        case .nonAuthoritativeInformation:  return "Non-Authoritative Information"
        case .noContent:                    return "No Content"
        case .resetContent:                 return "Reset Content"
        case .partialContent:               return "Partial Content"
        case .multiStatus:                  return "Multi-Status"
        case .alreadyReported:              return "Already Reported"
        case .imUsed:                       return "IM Used"
        case .unknown(let code):            return "Unknown Success code: \(code)"
        }
    }
}

3xx: Redirection Messages

The 3xx category of status codes indicates that the client must take additional action to complete the request. In many cases, URLSession handles these redirects automatically under the hood. However, being able to explicitly identify them is vital for advanced scenarios, such as optimizing cache performance with 304 Not Modified or debugging unexpected URL changes.

By including redirection messages in our service, we gain full visibility into the “hops” our network requests take before reaching their final destination. This is particularly useful when working with legacy APIs or complex content delivery networks (CDNs).

/// 3xx Redirection: Further action needs to be taken by the user agent to fulfill the request.
enum RedirectionMessages: Error, HTTPResponseDescription {
    case useProxy
    case found
    case seeOther
    case notModified
    case useProxyForAuthentication
    case temporaryRedirect
    case permanentRedirect
    case unknown(Int)

    init(code: Int) {
        switch code {
        case 300: self = .useProxy
        case 302: self = .found
        case 303: self = .seeOther
        case 304: self = .notModified
        case 305: self = .useProxyForAuthentication
        case 307: self = .temporaryRedirect
        case 308: self = .permanentRedirect
        default:  self = .unknown(code)
        }
    }

    var statusCode: Int {
        switch self {
        case .useProxy:                   return 300
        case .found:                      return 302
        case .seeOther:                   return 303
        case .notModified:                return 304
        case .useProxyForAuthentication:  return 305
        case .temporaryRedirect:          return 307
        case .permanentRedirect:          return 308
        case .unknown(let code):          return code
        }
    }

    var description: String {
        switch self {
        case .useProxy:
            return "Multiple Choices" 
        case .found:
            return "Found"
        case .seeOther:
            return "See Other"
        case .notModified:
            return "Not Modified"
        case .useProxyForAuthentication:
            return "Use Proxy"
        case .temporaryRedirect:
            return "Temporary Redirect"
        case .permanentRedirect:
            return "Permanent Redirect"
        case .unknown(let code):
            return "Unknown Redirection code: \(code)"
        }
    }
}

4xx: Client Error Responses

This is where things get interesting — and where your app’s logic needs to be the sharpest. The 4xx category represents errors where the request contains bad syntax or cannot be fulfilled. In short: the client (your app) did something the server didn’t like, or the user needs to provide more information.

Properly handling 4xx errors is the difference between an app that just says “Error” and one that intelligently guides the user. For instance, a 401 Unauthorized should trigger a login flow, while a 429 Too Many Requests should tell the user to slow down rather than spamming the retry button.

/// 4xx Client Error: The request contains bad syntax or cannot be fulfilled.
enum ClientErrorResponses: Error, HTTPResponseDescription {
    case badRequest
    case unauthorized
    case forbidden
    case notFound
    case methodNotAllowed
    case notAcceptable
    case proxyAuthenticationRequired
    case requestTimeout
    case conflict
    case gone
    case lengthRequired
    case preconditionFailed
    case payloadTooLarge
    case URITooLong
    case unsupportedMediaType
    case rangeNotSatisfiable
    case expectationFailed
    case misdirectedRequest
    case unProcessableEntity
    case locked
    case failedDependency
    case upgradeRequired
    case preconditionRequired
    case tooManyRequests
    case requestHeaderFieldsTooLarge
    case unavailableForLegalReasons
    case unknown(Int)

    init(code: Int) {
        switch code {
        case 400: self = .badRequest
        case 401: self = .unauthorized
        case 403: self = .forbidden
        case 404: self = .notFound
        case 405: self = .methodNotAllowed
        case 406: self = .notAcceptable
        case 407: self = .proxyAuthenticationRequired
        case 408: self = .requestTimeout
        case 409: self = .conflict
        case 410: self = .gone
        case 411: self = .lengthRequired
        case 412: self = .preconditionFailed
        case 413: self = .payloadTooLarge
        case 414: self = .URITooLong
        case 415: self = .unsupportedMediaType
        case 416: self = .rangeNotSatisfiable
        case 417: self = .expectationFailed
        case 421: self = .misdirectedRequest
        case 422: self = .unProcessableEntity
        case 423: self = .locked
        case 424: self = .failedDependency
        case 426: self = .upgradeRequired
        case 428: self = .preconditionRequired
        case 429: self = .tooManyRequests
        case 431: self = .requestHeaderFieldsTooLarge
        case 451: self = .unavailableForLegalReasons
        default:  self = .unknown(code)
        }
    }

    var statusCode: Int {
        switch self {
        case .badRequest:                   return 400
        case .unauthorized:                 return 401
        case .forbidden:                    return 403
        case .notFound:                     return 404
        case .methodNotAllowed:             return 405
        case .notAcceptable:                return 406
        case .proxyAuthenticationRequired:  return 407
        case .requestTimeout:               return 408
        case .conflict:                     return 409
        case .gone:                         return 410
        case .lengthRequired:               return 411
        case .preconditionFailed:           return 412
        case .payloadTooLarge:              return 413
        case .URITooLong:                   return 414
        case .unsupportedMediaType:         return 415
        case .rangeNotSatisfiable:          return 416
        case .expectationFailed:            return 417
        case .misdirectedRequest:           return 421
        case .unProcessableEntity:          return 422
        case .locked:                       return 423
        case .failedDependency:             return 424
        case .upgradeRequired:              return 426
        case .preconditionRequired:         return 428
        case .tooManyRequests:              return 429
        case .requestHeaderFieldsTooLarge:  return 431
        case .unavailableForLegalReasons:   return 451
        case .unknown(let code):            return code
        }
    }

    var description: String {
        switch self {
        case .badRequest:                   return "Bad Request"
        case .unauthorized:                 return "Unauthorized"
        case .forbidden:                    return "Forbidden"
        case .notFound:                     return "Not Found"
        case .methodNotAllowed:             return "Method Not Allowed"
        case .notAcceptable:                return "Not Acceptable"
        case .proxyAuthenticationRequired:  return "Proxy Authentication Required"
        case .requestTimeout:               return "Request Timeout"
        case .conflict:                     return "Conflict"
        case .gone:                         return "Gone"
        case .lengthRequired:               return "Length Required"
        case .preconditionFailed:           return "Precondition Failed"
        case .payloadTooLarge:              return "Payload Too Large"
        case .URITooLong:                   return "URI Too Long"
        case .unsupportedMediaType:         return "Unsupported Media Type"
        case .rangeNotSatisfiable:          return "Range Not Satisfiable"
        case .expectationFailed:            return "Expectation Failed"
        case .misdirectedRequest:           return "Misdirected Request"
        case .unProcessableEntity:          return "Unprocessable Entity"
        case .locked:                       return "Locked"
        case .failedDependency:             return "Failed Dependency"
        case .upgradeRequired:              return "Upgrade Required"
        case .preconditionRequired:         return "Precondition Required"
        case .tooManyRequests:              return "Too Many Requests"
        case .requestHeaderFieldsTooLarge:  return "Request Header Fields Too Large"
        case .unavailableForLegalReasons:   return "Unavailable For Legal Reasons"
        case .unknown(let code):            return "Unknown Client Error code: \(code)"
        }
    }
}

5xx: Server Error Responses

The 5xx category is the server’s way of saying, “It’s not you, it’s me.” These status codes indicate cases where the server is aware that it has encountered an error or is otherwise incapable of performing the request.

For an iOS developer, handling 5xx errors correctly is crucial for app stability. While a 4xx error might suggest a bug in your request logic, a 5xx error usually means the backend is having a bad day. Identifying a 503 Service Unavailable versus a 504 Gateway Timeout allows you to decide whether to trigger an immediate retry or to show a "Maintenance" screen to the user.

/// 5xx Server Error: The server failed to fulfill an apparently valid request.
enum ServerErrorResponses: Error, HTTPResponseDescription {
    case internalServerError
    case notImplemented
    case badGateway
    case serviceUnavailable
    case gatewayTimeout
    case httpVersionNotSupported
    case variantAlsoNegotiates
    case insufficientStorage
    case loopDetected
    case notExtended
    case networkAuthenticationRequired
    case unknown(Int)

    init(code: Int) {
        switch code {
        case 500: self = .internalServerError
        case 501: self = .notImplemented
        case 502: self = .badGateway
        case 503: self = .serviceUnavailable
        case 504: self = .gatewayTimeout
        case 505: self = .httpVersionNotSupported
        case 506: self = .variantAlsoNegotiates
        case 507: self = .insufficientStorage
        case 508: self = .loopDetected
        case 510: self = .notExtended
        case 511: self = .networkAuthenticationRequired
        default:  self = .unknown(code)
        }
    }

    var statusCode: Int {
        switch self {
        case .internalServerError:           return 500
        case .notImplemented:                return 501
        case .badGateway:                    return 502
        case .serviceUnavailable:            return 503
        case .gatewayTimeout:                return 504
        case .httpVersionNotSupported:       return 505
        case .variantAlsoNegotiates:         return 506
        case .insufficientStorage:           return 507
        case .loopDetected:                  return 508
        case .notExtended:                   return 510
        case .networkAuthenticationRequired: return 511
        case .unknown(let code):             return code
        }
    }

    var description: String {
        switch self {
        case .internalServerError:
            return "Internal Server Error"
        case .notImplemented:
            return "Not Implemented"
        case .badGateway:
            return "Bad Gateway"
        case .serviceUnavailable:
            return "Service Unavailable"
        case .gatewayTimeout:
            return "Gateway Timeout"
        case .httpVersionNotSupported:
            return "HTTP Version Not Supported"
        case .variantAlsoNegotiates:
            return "Variant Also Negotiates"
        case .insufficientStorage:
            return "Insufficient Storage"
        case .loopDetected:
            return "Loop Detected"
        case .notExtended:
            return "Not Extended"
        case .networkAuthenticationRequired:
            return "Network Authentication Required"
        case .unknown(let code):
            return "Unknown Server Error code: \(code)"
        }
    }
}

The Orchestrator: Unifying the Network Layer

Now that we have defined our granular categories, we need a single source of truth to manage them. This is where the NetworkHTTPResponseService comes in. It acts as a “Master Enum” — an orchestrator that takes a raw HTTPURLResponse and transforms it into a strictly typed, categorized result.

By using Associated Values, we can nest our specific enums (like ClientErrorResponses) inside this service. This allows our network layer to remain clean: instead of checking dozens of status codes, it simply checks which "category" the response falls into.

/// The main orchestrator service that unifies all HTTP response categories.
/// It simplifies error handling by wrapping specific groups into associated values.
enum NetworkHTTPResponseService: Error, Equatable, HTTPResponseDescription {

    // MARK: - Equatable Implementation
    /// Compares two responses based on their numeric status codes.
    static func == (lhs: NetworkHTTPResponseService, rhs: NetworkHTTPResponseService) -> Bool {
        return lhs.statusCode == rhs.statusCode
    }

    // MARK: - Cases
    case informationResponse(InformationalResponse)
    case successfulResponse(SuccessfulResponses)
    case redirectionMessages(RedirectionMessages)
    case clientErrorResponses(ClientErrorResponses)
    case serverErrorResponses(ServerErrorResponses)
    case unknownError(_ status: Int)
    case badRequest(codeError: NSURLErrorCode) // Handles system-level URL errors

    // MARK: - Initializer
    /// Automatically categorizes the response based on the HTTP status code range.
    init(urlResponse: HTTPURLResponse) {
        let statusCode = urlResponse.statusCode
        switch statusCode {
        case 100..<199: 
            self = .informationResponse(InformationalResponse(code: statusCode))
        case 200..<299: 
            self = .successfulResponse(SuccessfulResponses(code: statusCode))
        case 300..<399: 
            self = .redirectionMessages(RedirectionMessages(code: statusCode))
        case 400..<499: 
            self = .clientErrorResponses(ClientErrorResponses(code: statusCode))
        case 500..<599: 
            self = .serverErrorResponses(ServerErrorResponses(code: statusCode))
        default:        
            self = .unknownError(statusCode)
        }
    }

    // MARK: - Convenience Getters
    /// Safely unwraps the successful status if the response was a success.
    var successfulStatus: SuccessfulResponses? {
        if case .successfulResponse(let status) = self { return status }
        return nil
    }

    /// Safely unwraps the client error if the request was malformed or unauthorized.
    var clientError: ClientErrorResponses? {
        if case .clientErrorResponses(let status) = self { return status }
        return nil
    }

    // MARK: - HTTPResponseDescription Conformance
    var statusCode: Int {
        switch self {
        case .informationResponse(let code):  return code.statusCode
        case .successfulResponse(let code):   return code.statusCode
        case .redirectionMessages(let code):  return code.statusCode
        case .clientErrorResponses(let code): return code.statusCode
        case .serverErrorResponses(let code): return code.statusCode
        case .unknownError(let code):         return code
        case .badRequest(let codeError):      return codeError.statusCode
        }
    }

    var description: String {
        switch self {
        case .informationResponse(let code):
            return "Informational: \(code.description)"
        case .successfulResponse(let code):
            return "Success: \(code.description)"
        case .redirectionMessages(let code):
            return "Redirection: \(code.description)"
        case .clientErrorResponses(let code):
            return "Client Error: \(code.description)"
        case .serverErrorResponses(let code):
            return "Server Error: \(code.description)"
        case .unknownError(let code):
            return "Unknown Status Code: \(code)"
        case .badRequest(let code):
            return "Bad System Request: \(code.description)"
        }
    }
}

The Orchestrator: Unifying the Network Layer

// The main orchestrator service that unifies all HTTP response categories.
/// It simplifies error handling by wrapping specific groups into associated values.
enum NetworkHTTPResponseService: Error, Equatable, HTTPResponseDescription {

    // MARK: - Equatable Implementation
    /// Compares two responses based on their numeric status codes.
    static func == (lhs: NetworkHTTPResponseService, rhs: NetworkHTTPResponseService) -> Bool {
        return lhs.statusCode == rhs.statusCode
    }

    // MARK: - Cases
    case informationResponse(InformationalResponse)
    case successfulResponse(SuccessfulResponses)
    case redirectionMessages(RedirectionMessages)
    case clientErrorResponses(ClientErrorResponses)
    case serverErrorResponses(ServerErrorResponses)
    case unknownError(_ status: Int)
    case badRequest(codeError: NSURLErrorCode) // Handles system-level URL errors

    // MARK: - Initializer
    /// Automatically categorizes the response based on the HTTP status code range.
    init(urlResponse: HTTPURLResponse) {
        let statusCode = urlResponse.statusCode
        switch statusCode {
        case 100..<199: 
            self = .informationResponse(InformationalResponse(code: statusCode))
        case 200..<299: 
            self = .successfulResponse(SuccessfulResponses(code: statusCode))
        case 300..<399: 
            self = .redirectionMessages(RedirectionMessages(code: statusCode))
        case 400..<499: 
            self = .clientErrorResponses(ClientErrorResponses(code: statusCode))
        case 500..<599: 
            self = .serverErrorResponses(ServerErrorResponses(code: statusCode))
        default:        
            self = .unknownError(statusCode)
        }
    }

    // MARK: - Convenience Getters
    /// Safely unwraps the successful status if the response was a success.
    var successfulStatus: SuccessfulResponses? {
        if case .successfulResponse(let status) = self { return status }
        return nil
    }

    /// Safely unwraps the client error if the request was malformed or unauthorized.
    var clientError: ClientErrorResponses? {
        if case .clientErrorResponses(let status) = self { return status }
        return nil
    }

    // MARK: - HTTPResponseDescription Conformance
    var statusCode: Int {
        switch self {
        case .informationResponse(let code):  return code.statusCode
        case .successfulResponse(let code):   return code.statusCode
        case .redirectionMessages(let code):  return code.statusCode
        case .clientErrorResponses(let code): return code.statusCode
        case .serverErrorResponses(let code): return code.statusCode
        case .unknownError(let code):         return code
        case .badRequest(let codeError):      return codeError.statusCode
        }
    }

    var description: String {
        switch self {
        case .informationResponse(let code):
            return "Informational: \(code.description)"
        case .successfulResponse(let code):
            return "Success: \(code.description)"
        case .redirectionMessages(let code):
            return "Redirection: \(code.description)"
        case .clientErrorResponses(let code):
            return "Client Error: \(code.description)"
        case .serverErrorResponses(let code):
            return "Server Error: \(code.description)"
        case .unknownError(let code):
            return "Unknown Status Code: \(code)"
        case .badRequest(let code):
            return "Bad System Request: \(code.description)"
        }
    }
}

Putting It All Together: The fetch Implementation

This is the final piece of the puzzle. The fetch function is where we apply all the architectural groundwork we've laid. It leverages Swift Concurrency (async/await) and the new Typed Throws feature introduced in Swift 6.0 to provide a compile-time guarantee that this function can only throw a NetworkHTTPResponseService error.

Implementation Details
The beauty of this method lies in its two-stage validation:

Transport Level: We catch system-level URLError (like timeouts or lack of connection) and map them to our NSURLErrorCode.
Protocol Level: Once we have an HTTPURLResponse, we use our orchestrator to decide if the status code represents success or a specific failure.

/// Fetches and decodes data from a given URL.
/// - Parameter url: The endpoint to request data from.
/// - Returns: A decoded object of type T.
/// - Throws: A `NetworkHTTPResponseService` error, providing specific details about the failure.
func fetch<T>(_ url: URL) async throws(NetworkHTTPResponseService) -> T where T : Decodable {
    let data: Data
    let response: URLResponse

    // Stage 1: Attempt the network transport
    do {
        (data, response) = try await urlSession.data(from: url)
    } catch let error as URLError {
        // Map low-level system errors to our structured NSURLErrorCode
        switch error.code {
        case .badURL:
            throw NetworkHTTPResponseService.badRequest(codeError: .badURL)
        case .timedOut:
            throw NetworkHTTPResponseService.badRequest(codeError: .timedOut)
        default:
            throw NetworkHTTPResponseService.badRequest(codeError: .unknown)
        }
    } catch {
        // Fallback for any other non-URLError exceptions
        throw NetworkHTTPResponseService.badRequest(codeError: .unknown)
    }

    // Stage 2: Validate the HTTP protocol response
    guard let httpResponse = response as? HTTPURLResponse else {
        throw NetworkHTTPResponseService.badRequest(codeError: .invalidResponse)
    }

    // Convert the status code into our categorized enum
    let responseStatus = NetworkHTTPResponseService(urlResponse: httpResponse)

    // Stage 3: Handle the categorized result
    switch responseStatus {
    case .successfulResponse:
        do {
            // Only attempt decoding if the server returned a 2xx status
            let result = try decoder.decode(T.self, from: data)
            return result
        } catch {
            // Wrap decoding failures as a specific badRequest subtype
            throw NetworkHTTPResponseService.badRequest(codeError: .decodingError)
        }
    default:
        // Automatically throw 1xx, 3xx, 4xx, or 5xx errors
        throw responseStatus
    }
}

Key Takeaways for Your Network Layer
Typed Throws (throws(NetworkHTTPResponseService)): By specifying the error type, we eliminate the need for the caller to cast a generic Error to our custom type. The compiler now knows exactly what to expect in the catch block.
Decoupled Decoding: Decoding only happens inside the .successfulResponse case. This prevents the app from trying to parse a JSON error body into a valid Data Model, which is a common source of "Silent Failures."
Readability: The switch responseStatus block is incredibly clean. It clearly separates the "Happy Path" from everything else, making the function easy to scan at a glance.
Final Conclusion
Building a professional network layer is not just about sending requests; it’s about managing expectations. By categorizing every possible outcome into a strict hierarchy of enums, we’ve transformed a fragile part of our app into a resilient, predictable service.

Your UI can now respond with surgical precision to a 401 Unauthorized or a 504 Gateway Timeout, significantly improving the user experience and making your code a joy to maintain.

Thank you so much for sticking with me until the very end!
I’ve put a lot of thought and effort into this implementation because I believe that clean, predictable code is the foundation of any great app. My goal was to provide you with a “production-ready” pattern that you can literally copy, paste, and adapt into your own projects today.

If this guide helped you rethink your error handling or saved you a few hours of debugging, I would truly appreciate your support.

Clap for this article to help others find it.
Follow me here on Medium for more deep dives into Swift, Clean Architecture, and iOS development.
Share your thoughts in the comments — I’d love to hear how you handle networking edge cases!

Happy coding, and let’s keep building better apps together! 🚀

full source code

my linkedin