-- introduce ClientError as a shared superclass for all 4xx errors

 -- Previously, AuthenticationError, InvalidRequestError, and NotFoundError all inherited directly from the base Error class, making it impossible to rescue "any client error" without listing them individually.

 -- This adds ClientError as a middle tier so callers can choose their rescue granularity — catch a specific 4xx, catch all 4xx, or catch everything without breaking any existing rescue clauses.

  Closes #1 (partial — request_id and JobFailedError deferred, see issue)

Author: MuhammadIbtisam

lib/crewai/errors.rb

@@ -3,11 +3,13 @@
 module CrewAI
   class Error < StandardError; end
 
-  class AuthenticationError < Error; end
+  class ClientError < Error; end
 
-  class InvalidRequestError < Error; end
+  class AuthenticationError < ClientError; end
 
-  class NotFoundError < Error; end
+  class InvalidRequestError < ClientError; end
+
+  class NotFoundError < ClientError; end
 
   class ServerError < Error; end
 

ruby-crewai.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ["78165374+MuhammadIbtisam@users.noreply.github.com"]
 
   spec.summary = "Ruby client for the CrewAI AMP HTTP API"
-  spec.description = "A minimal, production-grade Ruby client for CrewAI AMP REST endpoints: inputs, kickoff, status, and resume."
+  spec.description = "A minimal, production-grade Ruby client for CrewAI AMP REST endpoints: healthcheck, inputs, kickoff, status, and resume."
   spec.homepage = "https://github.com/MuhammadIbtisam/ruby-crewai"
   spec.license = "MIT"
 

spec/crewai/client/error_handling_spec.rb

@@ -10,6 +10,37 @@
   let(:client) { described_class.new(configuration: configuration) }
   let(:uri_base) { "https://test.crewai.com" }
 
+  describe "4xx errors are rescuable as CrewAI::ClientError" do
+    {
+      "401" => [401, "Unauthorized", CrewAI::AuthenticationError],
+      "422" => [422, "Bad input", CrewAI::InvalidRequestError],
+      "404" => [404, "Not found", CrewAI::NotFoundError]
+    }.each do |label, (status, message, klass)|
+      context "when the server returns #{label} (#{klass})" do
+        before do
+          stub_request(:get, "#{uri_base}/healthcheck")
+            .to_return(
+              status: status,
+              body: { "message" => message }.to_json,
+              headers: { "Content-Type" => "application/json" }
+            )
+        end
+
+        it "raises #{klass}" do
+          expect { client.healthcheck }.to raise_error(klass)
+        end
+
+        it "is rescuable as CrewAI::ClientError" do
+          expect { client.healthcheck }.to raise_error(CrewAI::ClientError)
+        end
+
+        it "is rescuable as CrewAI::Error" do
+          expect { client.healthcheck }.to raise_error(CrewAI::Error)
+        end
+      end
+    end
+  end
+
   describe "transport errors" do
     context "when the request times out" do
       before do
@@ -32,6 +63,17 @@
         expect { client.healthcheck }.to raise_error(CrewAI::ConnectionError, /connection refused/)
       end
     end
+
+    context "when an SSL error occurs" do
+      before do
+        stub_request(:get, "#{uri_base}/healthcheck")
+          .to_raise(Faraday::SSLError.new("SSL certificate verify failed"))
+      end
+
+      it "raises CrewAI::ConnectionError" do
+        expect { client.healthcheck }.to raise_error(CrewAI::ConnectionError, /SSL certificate verify failed/)
+      end
+    end
   end
 
   describe "unexpected HTTP status (catch-all)" do