Propagate API Gateway errors with custom exception

Introduces ApiGatewayException to propagate API Gateway error responses and status codes to the client. Updates ApiGatewayClient to throw this exception on failed responses, registers a renderable handler in the service provider, and adds a test to verify error propagation.

Author: KroderDev

README.md

@@ -24,7 +24,7 @@ This package provides a robust foundation for building Laravel-based microservic
   Easily enable, disable, or rename middleware via configuration, and use convenient groups like `microservice.auth` group for full authentication and authorization in one step.
 
 - **HTTP Client Macros:**
-  Pre-configured HTTP clients for communicating with your API Gateway or other services. When a request is available, these macros automatically forward the current correlation ID header.
+  Pre-configured HTTP clients for communicating with your API Gateway or other services. They automatically forward the current correlation ID header and propagate gateway errors to the caller.
 
 - **Ready-to-publish Configuration:**  
   All settings are customizable via a single config file, making it easy to adapt the package to your environment.
@@ -112,8 +112,6 @@ Route::middleware(['jwt.auth'])->group(function () {
 }
 ```
 
----
-
 ### LoadAccess
 
 **Alias**: the string you assign to `load_access` in `middleware_aliases`, e.g. `load.access`.  
@@ -298,6 +296,12 @@ When enabled (default), visiting `/api/health` returns:
 }
 ```
 
+### HTTP Client Macros
+
+Use `Http::apiGateway()` and its related macros for service-to-service calls. Each macro forwards the current correlation ID header when available.
+
+If the gateway responds with an error (for example, a `503`), an `ApiGatewayException` is thrown and automatically returned to the client with the same status code.
+
 ---
 
 ## Public Release and Roadmap

src/Exceptions/ApiGatewayException.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Kroderdev\LaravelMicroserviceCore\Exceptions;
+
+use Symfony\Component\HttpKernel\Exception\HttpException;
+
+class ApiGatewayException extends HttpException
+{
+    protected array $data;
+
+    public function __construct(int $statusCode, array $data = [], string $message = '', \Throwable $previous = null, array $headers = [], int $code = 0)
+    {
+        parent::__construct($statusCode, $message ?: 'API Gateway Error', $previous, $headers, $code);
+        $this->data = $data;
+    }
+
+    public function getData(): array
+    {
+        return $this->data;
+    }
+}

src/Providers/MicroserviceServiceProvider.php

@@ -2,13 +2,14 @@
 
 namespace Kroderdev\LaravelMicroserviceCore\Providers;
 
-use Illuminate\Foundation\Http\Kernel;
+use Illuminate\Contracts\Debug\ExceptionHandler;
 use Illuminate\Routing\Router;
 use Illuminate\Support\Facades\Gate;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\ServiceProvider;
 use Kroderdev\LaravelMicroserviceCore\Contracts\AccessUserInterface;
 use Kroderdev\LaravelMicroserviceCore\Contracts\ApiGatewayClientInterface;
+use Kroderdev\LaravelMicroserviceCore\Exceptions\ApiGatewayException;
 use Kroderdev\LaravelMicroserviceCore\Http\HealthCheckController;
 use Kroderdev\LaravelMicroserviceCore\Http\Middleware\LoadAccess;
 use Kroderdev\LaravelMicroserviceCore\Http\Middleware\PermissionMiddleware;
@@ -115,7 +116,7 @@ public function boot(Router $router): void
                 ->withHeaders($correlation ? [$header => $correlation] : [])
                 ->baseUrl(config('microservice.api_gateway.url'))
                 ->timeout(5)
-                ->retry(2, 100);
+                ->retry(2, 100, throw: false);
         });
 
         Http::macro('apiGatewayDirect', function () {
@@ -139,7 +140,7 @@ public function boot(Router $router): void
                 ->withHeaders($correlation ? [$header => $correlation] : [])
                 ->baseUrl(config('microservice.api_gateway.url'))
                 ->timeout(5)
-                ->retry(2, 100);
+                ->retry(2, 100, throw: false);
         });
 
         Http::macro('apiGatewayDirectWithToken', function (string $token) {
@@ -153,5 +154,10 @@ public function boot(Router $router): void
                 ->baseUrl(config('microservice.api_gateway.url'))
                 ->timeout(5);
         });
+
+        // Exceptions
+        $this->app->make(ExceptionHandler::class)->renderable(function (ApiGatewayException $e, $request) {
+            return response()->json($e->getData(), $e->getStatusCode());
+        });
     }
 }

src/Services/ApiGatewayClient.php

@@ -5,6 +5,7 @@
 use Illuminate\Http\Client\PendingRequest;
 use Illuminate\Support\Facades\Http;
 use Kroderdev\LaravelMicroserviceCore\Contracts\ApiGatewayClientInterface;
+use Kroderdev\LaravelMicroserviceCore\Exceptions\ApiGatewayException;
 
 class ApiGatewayClient implements ApiGatewayClientInterface
 {
@@ -37,21 +38,43 @@ public static function directWithToken(string $token): static
 
     public function get(string $uri, array $query = [])
     {
-        return $this->http->get($uri, $query);
+        return $this->handleResponse(
+            $this->http->get($uri, $query)
+        );
     }
 
     public function post(string $uri, array $data = [])
     {
-        return $this->http->post($uri, $data);
+        return $this->handleResponse(
+            $this->http->delete($uri)
+        );
     }
 
     public function put(string $uri, array $data = [])
     {
-        return $this->http->put($uri, $data);
+        return $this->handleResponse(
+            $this->http->delete($uri)
+        );
     }
 
     public function delete(string $uri)
     {
-        return $this->http->delete($uri);
+        return $this->handleResponse(
+            $this->http->delete($uri)
+        );
+    }
+
+    protected function handleResponse($response)
+    {
+        if (is_object($response) && method_exists($response, 'failed') && $response->failed()) {
+            $data = method_exists($response, 'json') ? $response->json() : [];
+
+            throw new ApiGatewayException(
+                method_exists($response, 'status') ? $response->status() : 500,
+                is_array($data) ? $data : []
+            );
+        }
+
+        return $response;
     }
 }

tests/Services/ApiGatewayErrorTest.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Tests\Services;
+
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Route;
+use Orchestra\Testbench\TestCase;
+use Kroderdev\LaravelMicroserviceCore\Contracts\ApiGatewayClientInterface;
+use Kroderdev\LaravelMicroserviceCore\Providers\MicroserviceServiceProvider;
+use Kroderdev\LaravelMicroserviceCore\Services\ApiGatewayClient;
+
+class ApiGatewayErrorTest extends TestCase
+{
+    protected function getPackageProviders($app)
+    {
+        return [MicroserviceServiceProvider::class];
+    }
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Http::fake(['*' => Http::response(['error' => 'unavailable'], 503)]);
+
+        Route::get('/gateway-error', function () {
+            return app(ApiGatewayClient::class)->get('/fail');
+        });
+    }
+
+    /** @test */
+    public function propagates_gateway_status_code()
+    {
+        $this->get('/gateway-error')
+            ->assertStatus(503)
+            ->assertJson(['error' => 'unavailable']);
+    }
+}