Enhance TransporterException with response details

TransporterException now includes the HTTP response, response body, and status code, improving error diagnostics. HttpTransporter passes these details when throwing TransporterException. Added tests to verify exception behavior with various error responses.

Author: erdiarikan

src/Exceptions/TransporterException.php

@@ -6,14 +6,43 @@
 
 use Exception;
 use Psr\Http\Client\ClientExceptionInterface;
+use Psr\Http\Message\ResponseInterface;
 
 final class TransporterException extends Exception
 {
-    /**
-     * Creates a new Exception instance.
-     */
-    public function __construct(ClientExceptionInterface $exception)
+    private readonly ?ResponseInterface $response;
+
+    private readonly ?string $responseBody;
+
+    public function __construct(
+        ClientExceptionInterface $exception,
+        ?ResponseInterface $response = null,
+        ?string $responseBody = null
+    ) {
+        $this->response = $response;
+        $this->responseBody = $responseBody;
+
+        $message = $exception->getMessage();
+
+        if ($responseBody !== null && $responseBody !== '') {
+            $message .= ' | Response: ' . $responseBody;
+        }
+
+        parent::__construct($message, $response?->getStatusCode() ?? 0, $exception);
+    }
+
+    public function getResponse(): ?ResponseInterface
+    {
+        return $this->response;
+    }
+
+    public function getResponseBody(): ?string
+    {
+        return $this->responseBody;
+    }
+
+    public function getStatusCode(): int
     {
-        parent::__construct($exception->getMessage(), 0, $exception);
+        return $this->response?->getStatusCode() ?? 0;
     }
-}
+}

src/Transporters/HttpTransporter.php

@@ -140,11 +140,16 @@ private function sendRequest(Closure $callable): ResponseInterface
         try {
             return $callable();
         } catch (ClientExceptionInterface $clientException) {
+            $response = null;
+            $responseBody = null;
+
             if ($clientException instanceof ClientException) {
-                $this->throwIfJsonError($clientException->getResponse(), (string) $clientException->getResponse()->getBody());
+                $response = $clientException->getResponse();
+                $responseBody = (string) $response->getBody();
+                $this->throwIfJsonError($response, $responseBody);
             }
 
-            throw new TransporterException($clientException);
+            throw new TransporterException($clientException, $response, $responseBody);
         }
     }
 

tests/Transporters/HttpTransporter.php

@@ -652,3 +652,103 @@
 
     $this->http->requestObject($payload);
 });
+
+test('transporter exception includes response body for non-json client errors', function () {
+    $payload = Payload::list('models');
+
+    $baseUri = BaseUri::from('api.openai.com');
+    $headers = Headers::withAuthorization(ApiKey::from('foo'));
+    $queryParams = QueryParams::create();
+
+    $responseBody = 'Bad Request: Invalid model parameter provided';
+
+    $this->client
+        ->shouldReceive('sendRequest')
+        ->once()
+        ->andThrow(new \GuzzleHttp\Exception\ClientException(
+            message: 'Client error: 400 Bad Request',
+            request: $payload->toRequest($baseUri, $headers, $queryParams),
+            response: new Response(400, ['Content-Type' => 'text/plain'], $responseBody)
+        ));
+
+    expect(fn () => $this->http->requestObject($payload))->toThrow(function (TransporterException $e) use ($responseBody) {
+        expect($e->getMessage())->toContain($responseBody)
+            ->and($e->getResponseBody())->toBe($responseBody)
+            ->and($e->getStatusCode())->toBe(400)
+            ->and($e->getResponse())->not->toBeNull();
+    });
+});
+
+test('transporter exception includes response body for html error responses', function () {
+    $payload = Payload::list('models');
+
+    $baseUri = BaseUri::from('api.openai.com');
+    $headers = Headers::withAuthorization(ApiKey::from('foo'));
+    $queryParams = QueryParams::create();
+
+    $responseBody = '<html><body><h1>502 Bad Gateway</h1></body></html>';
+
+    $this->client
+        ->shouldReceive('sendRequest')
+        ->once()
+        ->andThrow(new \GuzzleHttp\Exception\ClientException(
+            message: 'Server error: 502 Bad Gateway',
+            request: $payload->toRequest($baseUri, $headers, $queryParams),
+            response: new Response(502, ['Content-Type' => 'text/html'], $responseBody)
+        ));
+
+    expect(fn () => $this->http->requestObject($payload))->toThrow(function (TransporterException $e) use ($responseBody) {
+        expect($e->getMessage())->toContain($responseBody)
+            ->and($e->getResponseBody())->toBe($responseBody)
+            ->and($e->getStatusCode())->toBe(502);
+    });
+});
+
+test('transporter exception includes openrouter style error response', function () {
+    $payload = Payload::list('models');
+
+    $baseUri = BaseUri::from('api.openai.com');
+    $headers = Headers::withAuthorization(ApiKey::from('foo'));
+    $queryParams = QueryParams::create();
+
+    $responseBody = json_encode([
+        'message' => 'Provider returned error',
+        'code' => 400,
+        'metadata' => ['provider' => 'anthropic'],
+    ]);
+
+    $this->client
+        ->shouldReceive('sendRequest')
+        ->once()
+        ->andThrow(new \GuzzleHttp\Exception\ClientException(
+            message: 'Client error: 400 Bad Request',
+            request: $payload->toRequest($baseUri, $headers, $queryParams),
+            response: new Response(400, ['Content-Type' => 'application/json'], $responseBody)
+        ));
+
+    expect(fn () => $this->http->requestObject($payload))->toThrow(function (TransporterException $e) use ($responseBody) {
+        expect($e->getMessage())->toContain('Provider returned error')
+            ->and($e->getResponseBody())->toBe($responseBody)
+            ->and($e->getStatusCode())->toBe(400);
+    });
+});
+
+test('transporter exception getters work without response', function () {
+    $payload = Payload::list('models');
+
+    $baseUri = BaseUri::from('api.openai.com');
+    $headers = Headers::withAuthorization(ApiKey::from('foo'));
+    $queryParams = QueryParams::create();
+
+    $this->client
+        ->shouldReceive('sendRequest')
+        ->once()
+        ->andThrow(new ConnectException('Could not resolve host.', $payload->toRequest($baseUri, $headers, $queryParams)));
+
+    expect(fn () => $this->http->requestObject($payload))->toThrow(function (TransporterException $e) {
+        expect($e->getMessage())->toBe('Could not resolve host.')
+            ->and($e->getResponseBody())->toBeNull()
+            ->and($e->getStatusCode())->toBe(0)
+            ->and($e->getResponse())->toBeNull();
+    });
+});