Implement complete exception hierarchy with ClientException and ServerException

Author: Mohamed Khaled

src/Providers/Http/Exception/ClientException.php

@@ -4,6 +4,8 @@
 
 namespace WordPress\AiClient\Providers\Http\Exception;
 
+use WordPress\AiClient\Providers\Http\DTO\Response;
+
 /**
  * Exception thrown for 4xx HTTP client errors.
  *
@@ -25,6 +27,51 @@ class ClientException extends RequestException
     public static function fromBadRequestResponse(string $errorDetail = 'Invalid request parameters'): self
     {
         $message = sprintf('Bad request (400): %s', $errorDetail);
-        return new self($message);
+        return new self($message, 400);
+    }
+
+    /**
+     * Creates a ClientException from a client error response (4xx).
+     *
+     * This method extracts error details from common API response formats
+     * and creates an exception with a descriptive message and status code.
+     *
+     * @since n.e.x.t
+     *
+     * @param Response $response The HTTP response that failed.
+     * @return self
+     */
+    public static function fromClientError(Response $response): self
+    {
+        $errorMessage = sprintf(
+            'Client error (%d): Request was rejected due to client-side issue',
+            $response->getStatusCode()
+        );
+
+        // Handle common error formats in API responses
+        $data = $response->getData();
+        if (
+            is_array($data) &&
+            isset($data['error']) &&
+            is_array($data['error']) &&
+            isset($data['error']['message']) &&
+            is_string($data['error']['message'])
+        ) {
+            $errorMessage .= ' - ' . $data['error']['message'];
+        } elseif (
+            is_array($data) &&
+            isset($data['error']) &&
+            is_string($data['error'])
+        ) {
+            $errorMessage .= ' - ' . $data['error'];
+        } elseif (
+            is_array($data) &&
+            isset($data['message']) &&
+            is_string($data['message'])
+        ) {
+            $errorMessage .= ' - ' . $data['message'];
+        }
+
+        return new self($errorMessage, $response->getStatusCode());
     }
 }

src/Providers/Http/Exception/ServerException.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Http\Exception;
+
+use WordPress\AiClient\Providers\Http\DTO\Response;
+
+/**
+ * Exception thrown for 5xx HTTP server errors.
+ *
+ * This represents errors where the server failed to fulfill
+ * a valid request due to internal server errors.
+ *
+ * @since n.e.x.t
+ */
+class ServerException extends RequestException
+{
+    /**
+     * Creates a ServerException from a server error response.
+     *
+     * This method extracts error details from common API response formats
+     * and creates an exception with a descriptive message and status code.
+     *
+     * @since n.e.x.t
+     *
+     * @param Response $response The HTTP response that failed.
+     * @return self
+     */
+    public static function fromServerError(Response $response): self
+    {
+        $errorMessage = sprintf(
+            'Server error (%d): Request failed due to server-side issue',
+            $response->getStatusCode()
+        );
+
+        // Handle common error formats in API responses
+        $data = $response->getData();
+        if (
+            is_array($data) &&
+            isset($data['error']) &&
+            is_array($data['error']) &&
+            isset($data['error']['message']) &&
+            is_string($data['error']['message'])
+        ) {
+            $errorMessage .= ' - ' . $data['error']['message'];
+        } elseif (
+            is_array($data) &&
+            isset($data['error']) &&
+            is_string($data['error'])
+        ) {
+            $errorMessage .= ' - ' . $data['error'];
+        } elseif (
+            is_array($data) &&
+            isset($data['message']) &&
+            is_string($data['message'])
+        ) {
+            $errorMessage .= ' - ' . $data['message'];
+        }
+
+        return new self($errorMessage, $response->getStatusCode());
+    }
+}

src/Providers/Http/Util/ResponseUtil.php

@@ -7,6 +7,7 @@
 use WordPress\AiClient\Providers\Http\DTO\Response;
 use WordPress\AiClient\Providers\Http\Exception\ClientException;
 use WordPress\AiClient\Providers\Http\Exception\ResponseException;
+use WordPress\AiClient\Providers\Http\Exception\ServerException;
 
 /**
  * Class with static utility methods to process HTTP responses.
@@ -16,31 +17,48 @@
 class ResponseUtil
 {
     /**
-     * Throws a response exception if the given response is not successful.
+     * Throws an appropriate exception if the given response is not successful.
      *
      * This method checks the HTTP status code of the response and throws
-     * a ResponseException if the status code indicates an error (i.e., not in the
-     * 2xx range). It also attempts to extract a more detailed error message from
-     * the response body if available.
+     * the appropriate exception type based on the status code range:
+     * - 4xx: ClientException (client errors)
+     * - 5xx: ServerException (server errors)
+     * - Other unsuccessful responses: ResponseException (malformed responses)
      *
      * @since 0.1.0
      *
      * @param Response $response The HTTP response to check.
-     * @throws ResponseException If the response is not successful.
+     * @throws ClientException If the response indicates a client error (4xx).
+     * @throws ServerException If the response indicates a server error (5xx).
+     * @throws ResponseException If the response format is unexpected.
      */
     public static function throwIfNotSuccessful(Response $response): void
     {
         if ($response->isSuccessful()) {
             return;
         }
 
-        // Check for 400 Bad Request responses indicating invalid request data
-        if ($response->getStatusCode() === 400) {
-            $body = (string) $response->getBody();
-            $errorDetail = $body ? substr($body, 0, 200) : 'Invalid request parameters';
-            throw ClientException::fromBadRequestResponse($errorDetail);
+        $statusCode = $response->getStatusCode();
+
+        // 4xx Client Errors
+        if ($statusCode >= 400 && $statusCode < 500) {
+            // Special handling for 400 Bad Request
+            if ($statusCode === 400) {
+                $body = (string) $response->getBody();
+                $errorDetail = $body ? substr($body, 0, 200) : 'Invalid request parameters';
+                throw ClientException::fromBadRequestResponse($errorDetail);
+            }
+            // General 4xx client errors
+            throw ClientException::fromClientError($response);
+        }
+
+        // 5xx Server Errors
+        if ($statusCode >= 500 && $statusCode < 600) {
+            throw ServerException::fromServerError($response);
         }
 
+        // Other unsuccessful responses (3xx redirects, etc.) - these should be rare
+        // as most HTTP clients handle redirects automatically
         throw ResponseException::fromBadResponse($response);
     }
 }