phase 1 and 2

app/Services/JobApi/Exceptions/ApiException.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Services\JobApi\Exceptions;
+
+use Exception;
+
+class ApiException extends Exception
+{
+    public function __construct(
+        string $message,
+        public readonly string $apiSource,
+        public readonly ?array $context = null,
+        int $code = 0,
+        ?\Throwable $previous = null
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+
+    public function getContext(): array
+    {
+        return array_merge([
+            'api_source' => $this->apiSource,
+            'message' => $this->getMessage(),
+            'code' => $this->getCode(),
+        ], $this->context ?? []);
+    }
+}

app/Services/JobApi/Exceptions/RateLimitException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Services\JobApi\Exceptions;
+
+class RateLimitException extends ApiException
+{
+    public function __construct(
+        string $apiSource,
+        public readonly ?int $retryAfter = null,
+        array $context = []
+    ) {
+        $message = "Rate limit exceeded for {$apiSource}";
+        if ($this->retryAfter) {
+            $message .= ". Retry after {$this->retryAfter} seconds";
+        }
+
+        parent::__construct($message, $apiSource, $context, 429);
+    }
+}

app/Services/JobApi/Exceptions/TransformationException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Services\JobApi\Exceptions;
+
+class TransformationException extends ApiException
+{
+    public function __construct(
+        string $apiSource,
+        string $message = 'Failed to transform API response',
+        array $context = []
+    ) {
+        parent::__construct($message, $apiSource, $context);
+    }
+}