Add decodingError case to ClientError with response body context

Wrap decoding failures in HTTPResponse.decodeSuccessBody() and
decodeFailureBody() as ClientError.decodingError, preserving the raw
response body for downstream logging and debugging.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: BrentMifsud

Sources/Simplicity/HTTP/HTTPResponse.swift

@@ -72,16 +72,32 @@ public nonisolated struct HTTPResponse<Success: Decodable & Sendable, Failure: D
 
     /// Decodes `httpBody` into the `Success` type using the configured success decoder.
     /// - Returns: A value of type `Success`.
-    /// - Throws: Any decoding error thrown by the underlying decoder.
+    /// - Throws: `ClientError.decodingError` wrapping the underlying error and the raw response body.
     public func decodeSuccessBody() throws -> Success {
-        try successBodyDecoder(httpBody)
+        do {
+            return try successBodyDecoder(httpBody)
+        } catch {
+            throw ClientError.decodingError(
+                type: String(describing: Success.self),
+                responseBody: httpBody,
+                underlyingError: error
+            )
+        }
     }
 
     /// Decodes `httpBody` into the `Failure` type using the configured failure decoder.
     /// - Returns: A value of type `Failure`.
-    /// - Throws: Any decoding error thrown by the underlying decoder.
+    /// - Throws: `ClientError.decodingError` wrapping the underlying error and the raw response body.
     public func decodeFailureBody() throws -> Failure {
-        try failureBodyDecoder(httpBody)
+        do {
+            return try failureBodyDecoder(httpBody)
+        } catch {
+            throw ClientError.decodingError(
+                type: String(describing: Failure.self),
+                responseBody: httpBody,
+                underlyingError: error
+            )
+        }
     }
 }
 

Sources/Simplicity/Implementation/ClientError.swift

@@ -12,6 +12,7 @@ public nonisolated enum ClientError: Sendable, LocalizedError {
     case timedOut
     case cacheMiss
     case encodingError(type: String, underlyingError: any Error)
+    case decodingError(type: String, responseBody: Data, underlyingError: any Error)
     case transport(URLError)
     case middleware(middleware: any Middleware, underlyingError: any Error)
     case invalidResponse(String)
@@ -26,6 +27,8 @@ public nonisolated enum ClientError: Sendable, LocalizedError {
             "The request was cancelled"
         case let .encodingError(type, underlyingError):
             "Failed to encode \(type): \(underlyingError.localizedDescription)"
+        case let .decodingError(type, responseBody, underlyingError):
+            "Failed to decode \(type): \(underlyingError.localizedDescription)\nResponse body: \(String(data: responseBody, encoding: .utf8) ?? "<\(responseBody.count) bytes>")"
         case .transport(let error):
             error.localizedDescription
         case .invalidResponse(let details):

Tests/SimplicityTests/URLSessionHTTPClientTests.swift

@@ -440,6 +440,100 @@ private struct SuccessOnlyRequest: HTTPRequest {
     }
 }
 
+// MARK: - Decoding Error Tests
+
+@Suite("HTTPResponse Decoding Error Tests")
+struct HTTPResponseDecodingErrorTests {
+    @Test
+    func testDecodeSuccessBody_throwsDecodingError_withResponseBody() throws {
+        // Arrange — response body is valid JSON but wrong shape for SuccessModel
+        let mismatchedBody = Data("{\"unexpected\":\"field\"}".utf8)
+        let response = HTTPResponse<SuccessModel, ErrorModel>(
+            statusCode: .ok,
+            url: URL(string: "https://example.com/test")!,
+            headers: [:],
+            httpBody: mismatchedBody,
+            successBodyDecoder: { data in
+                try JSONDecoder().decode(SuccessModel.self, from: data)
+            },
+            failureBodyDecoder: { data in
+                try JSONDecoder().decode(ErrorModel.self, from: data)
+            }
+        )
+
+        // Act & Assert
+        do {
+            _ = try response.decodeSuccessBody()
+            Issue.record("Expected decodingError to be thrown")
+        } catch let error as ClientError {
+            guard case let .decodingError(type, responseBody, underlyingError) = error else {
+                Issue.record("Expected ClientError.decodingError, got: \(error)")
+                return
+            }
+            #expect(type == "SuccessModel")
+            #expect(responseBody == mismatchedBody)
+            #expect(underlyingError is DecodingError)
+        }
+    }
+
+    @Test
+    func testDecodeFailureBody_throwsDecodingError_withResponseBody() throws {
+        // Arrange — response body is not valid JSON at all
+        let invalidBody = Data("not json".utf8)
+        let response = HTTPResponse<SuccessModel, ErrorModel>(
+            statusCode: .badRequest,
+            url: URL(string: "https://example.com/test")!,
+            headers: [:],
+            httpBody: invalidBody,
+            successBodyDecoder: { data in
+                try JSONDecoder().decode(SuccessModel.self, from: data)
+            },
+            failureBodyDecoder: { data in
+                try JSONDecoder().decode(ErrorModel.self, from: data)
+            }
+        )
+
+        // Act & Assert
+        do {
+            _ = try response.decodeFailureBody()
+            Issue.record("Expected decodingError to be thrown")
+        } catch let error as ClientError {
+            guard case let .decodingError(type, responseBody, underlyingError) = error else {
+                Issue.record("Expected ClientError.decodingError, got: \(error)")
+                return
+            }
+            #expect(type == "ErrorModel")
+            #expect(responseBody == invalidBody)
+            #expect(underlyingError is DecodingError)
+        }
+    }
+
+    @Test
+    func testDecodingError_errorDescription_includesResponseBody() throws {
+        let body = Data("{\"wrong\":true}".utf8)
+        let error = ClientError.decodingError(
+            type: "SuccessModel",
+            responseBody: body,
+            underlyingError: DecodingError.keyNotFound(
+                AnyCodingKey(stringValue: "value"),
+                .init(codingPath: [], debugDescription: "No value for key 'value'")
+            )
+        )
+
+        let description = error.errorDescription ?? ""
+        #expect(description.contains("Failed to decode SuccessModel"))
+        #expect(description.contains("{\"wrong\":true}"))
+    }
+}
+
+/// A type-erased CodingKey for test assertions.
+private struct AnyCodingKey: CodingKey {
+    var stringValue: String
+    var intValue: Int?
+    init(stringValue: String) { self.stringValue = stringValue; self.intValue = nil }
+    init?(intValue: Int) { self.stringValue = "\(intValue)"; self.intValue = intValue }
+}
+
 // MARK: - Cache Tests
 
 @Suite("URLSessionHTTPClient Cache Tests")