feat!: rename errors to exceptions

stainless-app[bot] · stainless-app[bot] · commit b568600fb25d · 2025-08-27T05:14:56.000Z
diff --git a/README.md b/README.md
@@ -68,18 +68,18 @@ However, builders are also provided `(new Dog)->withName("Joey")`.
 
 ### Handling errors
 
-When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Scrapegraphai\Errors\APIError` will be thrown:
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Scrapegraphai\Core\Exceptions\APIException` will be thrown:
 
 ```php
 <?php
 
-use Scrapegraphai\Core\Errors\APIConnectionError;
+use Scrapegraphai\Core\Exceptions\APIConnectionException;
 
 try {
   $completedSmartscraper = $client->smartscraper->create(
     userPrompt: "Extract the product name, price, and description"
   );
-} catch (APIConnectionError $e) {
+} catch (APIConnectionException $e) {
   echo "The server could not be reached", PHP_EOL;
   var_dump($e->getPrevious());
 } catch (RateLimitError $_) {
@@ -92,19 +92,19 @@ try {
 
 Error codes are as follows:
 
-| Cause            | Error Type                 |
-| ---------------- | -------------------------- |
-| HTTP 400         | `BadRequestError`          |
-| HTTP 401         | `AuthenticationError`      |
-| HTTP 403         | `PermissionDeniedError`    |
-| HTTP 404         | `NotFoundError`            |
-| HTTP 409         | `ConflictError`            |
-| HTTP 422         | `UnprocessableEntityError` |
-| HTTP 429         | `RateLimitError`           |
-| HTTP >= 500      | `InternalServerError`      |
-| Other HTTP error | `APIStatusError`           |
-| Timeout          | `APITimeoutError`          |
-| Network error    | `APIConnectionError`       |
+| Cause            | Error Type                     |
+| ---------------- | ------------------------------ |
+| HTTP 400         | `BadRequestException`          |
+| HTTP 401         | `AuthenticationException`      |
+| HTTP 403         | `PermissionDeniedException`    |
+| HTTP 404         | `NotFoundException`            |
+| HTTP 409         | `ConflictException`            |
+| HTTP 422         | `UnprocessableEntityException` |
+| HTTP 429         | `RateLimitException`           |
+| HTTP >= 500      | `InternalServerException`      |
+| Other HTTP error | `APIStatusException`           |
+| Timeout          | `APITimeoutException`          |
+| Network error    | `APIConnectionException`       |
 
 ### Retries
 
diff --git a/src/Core/BaseClient.php b/src/Core/BaseClient.php
@@ -17,7 +17,7 @@
 use Scrapegraphai\Core\Contracts\BaseStream;
 use Scrapegraphai\Core\Conversion\Contracts\Converter;
 use Scrapegraphai\Core\Conversion\Contracts\ConverterSource;
-use Scrapegraphai\Core\Errors\APIStatusError;
+use Scrapegraphai\Core\Exceptions\APIStatusException;
 use Scrapegraphai\RequestOptions;
 
 /**
@@ -203,7 +203,7 @@ protected function sendRequest(
         }
 
         if ($code >= 400 && $code < 500) {
-            throw APIStatusError::from(request: $req, response: $rsp);
+            throw APIStatusException::from(request: $req, response: $rsp);
         }
 
         if ($code >= 500 && $retryCount < $opts->maxRetries) {
diff --git a/src/Core/Concerns/SdkPage.php b/src/Core/Concerns/SdkPage.php
@@ -7,7 +7,7 @@
 use Scrapegraphai\Client;
 use Scrapegraphai\Core\Conversion\Contracts\Converter;
 use Scrapegraphai\Core\Conversion\Contracts\ConverterSource;
-use Scrapegraphai\Core\Errors\APIStatusError;
+use Scrapegraphai\Core\Exceptions\APIStatusException;
 use Scrapegraphai\RequestOptions;
 
 /**
@@ -52,7 +52,7 @@ public function hasNextPage(): bool
      *
      * @return static of static<Item>
      *
-     * @throws APIStatusError
+     * @throws APIStatusException
      */
     public function getNextPage(): static
     {
diff --git a/src/Core/Errors/AuthenticationError.php b/src/Core/Errors/AuthenticationError.php
diff --git a/src/Core/Errors/BadRequestError.php b/src/Core/Errors/BadRequestError.php
diff --git a/src/Core/Errors/ConflictError.php b/src/Core/Errors/ConflictError.php
diff --git a/src/Core/Errors/InternalServerError.php b/src/Core/Errors/InternalServerError.php
diff --git a/src/Core/Errors/NotFoundError.php b/src/Core/Errors/NotFoundError.php
diff --git a/src/Core/Errors/PermissionDeniedError.php b/src/Core/Errors/PermissionDeniedError.php
diff --git a/src/Core/Errors/RateLimitError.php b/src/Core/Errors/RateLimitError.php
diff --git a/src/Core/Errors/UnprocessableEntityError.php b/src/Core/Errors/UnprocessableEntityError.php
diff --git a/src/Core/Exceptions/APIConnectionException.php b/src/Core/Exceptions/APIConnectionException.php
@@ -1,8 +1,8 @@
 <?php
 
-namespace Scrapegraphai\Core\Errors;
+namespace Scrapegraphai\Core\Exceptions;
 
-class APIConnectionError extends APIError
+class APIConnectionException extends APIException
 {
     /** @var string */
     protected const DESC = 'Scrapegraphai API Connection Error';
diff --git a/src/Core/Exceptions/APIException.php b/src/Core/Exceptions/APIException.php
@@ -1,11 +1,11 @@
 <?php
 
-namespace Scrapegraphai\Core\Errors;
+namespace Scrapegraphai\Core\Exceptions;
 
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
-class APIError extends ScrapegraphaiError
+class APIException extends ScrapegraphaiException
 {
     public ?int $status = null;
 
diff --git a/src/Core/Exceptions/APIStatusException.php b/src/Core/Exceptions/APIStatusException.php
@@ -1,12 +1,12 @@
 <?php
 
-namespace Scrapegraphai\Core\Errors;
+namespace Scrapegraphai\Core\Exceptions;
 
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 use Scrapegraphai\Core\Util;
 
-class APIStatusError extends APIError
+class APIStatusException extends APIException
 {
     /** @var string */
     protected const DESC = 'Scrapegraphai API Status Error';
@@ -39,15 +39,15 @@ public static function from(
         $status = $response->getStatusCode();
 
         $cls = match (true) {
-            400 === $status => BadRequestError::class,
-            401 === $status => AuthenticationError::class,
-            403 === $status => PermissionDeniedError::class,
-            404 === $status => NotFoundError::class,
-            409 === $status => ConflictError::class,
-            422 === $status => UnprocessableEntityError::class,
-            429 === $status => RateLimitError::class,
-            $status >= 500 => InternalServerError::class,
-            default => APIStatusError::class
+            400 === $status => BadRequestException::class,
+            401 === $status => AuthenticationException::class,
+            403 === $status => PermissionDeniedException::class,
+            404 === $status => NotFoundException::class,
+            409 === $status => ConflictException::class,
+            422 === $status => UnprocessableEntityException::class,
+            429 === $status => RateLimitException::class,
+            $status >= 500 => InternalServerException::class,
+            default => APIStatusException::class
         };
 
         return new $cls(request: $request, response: $response, message: $message);
diff --git a/src/Core/Exceptions/APITimeoutException.php b/src/Core/Exceptions/APITimeoutException.php
@@ -1,13 +1,13 @@
 <?php
 
-namespace Scrapegraphai\Core\Errors;
+namespace Scrapegraphai\Core\Exceptions;
 
 use Psr\Http\Message\RequestInterface;
 
-class APITimeoutError extends APIConnectionError
+class APITimeoutException extends APIConnectionException
 {
     /** @var string */
-    protected const DESC = 'Scrapegraphai API Timeout Error';
+    protected const DESC = 'Scrapegraphai API Timeout Exception';
 
     public function __construct(
         public RequestInterface $request,
diff --git a/src/Core/Exceptions/AuthenticationException.php b/src/Core/Exceptions/AuthenticationException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class AuthenticationException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Authentication Exception';
+}
diff --git a/src/Core/Exceptions/BadRequestException.php b/src/Core/Exceptions/BadRequestException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class BadRequestException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Bad Request Exception';
+}
diff --git a/src/Core/Exceptions/ConflictException.php b/src/Core/Exceptions/ConflictException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class ConflictException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Conflict Exception';
+}
diff --git a/src/Core/Exceptions/InternalServerException.php b/src/Core/Exceptions/InternalServerException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class InternalServerException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Internal Server Exception';
+}
diff --git a/src/Core/Exceptions/NotFoundException.php b/src/Core/Exceptions/NotFoundException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class NotFoundException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Not Found Exception';
+}
diff --git a/src/Core/Exceptions/PermissionDeniedException.php b/src/Core/Exceptions/PermissionDeniedException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class PermissionDeniedException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Permission Denied Exception';
+}
diff --git a/src/Core/Exceptions/RateLimitException.php b/src/Core/Exceptions/RateLimitException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class RateLimitException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Rate Limit Exception';
+}
diff --git a/src/Core/Exceptions/ScrapegraphaiException.php b/src/Core/Exceptions/ScrapegraphaiException.php
@@ -1,8 +1,8 @@
 <?php
 
-namespace Scrapegraphai\Core\Errors;
+namespace Scrapegraphai\Core\Exceptions;
 
-class ScrapegraphaiError extends \Exception
+class ScrapegraphaiException extends \Exception
 {
     /** @var string */
     protected const DESC = 'Scrapegraphai Error';
diff --git a/src/Core/Exceptions/UnprocessableEntityException.php b/src/Core/Exceptions/UnprocessableEntityException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Scrapegraphai\Core\Exceptions;
+
+class UnprocessableEntityException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Scrapegraphai Unprocessable Entity Exception';
+}

Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@`
`17`	`17`	`use Scrapegraphai\Core\Contracts\BaseStream;`
`18`	`18`	`use Scrapegraphai\Core\Conversion\Contracts\Converter;`
`19`	`19`	`use Scrapegraphai\Core\Conversion\Contracts\ConverterSource;`
`20`		`-use Scrapegraphai\Core\Errors\APIStatusError;`
	`20`	`+use Scrapegraphai\Core\Exceptions\APIStatusException;`
`21`	`21`	`use Scrapegraphai\RequestOptions;`
`22`	`22`
`23`	`23`	`/**`
`@@ -203,7 +203,7 @@ protected function sendRequest(`
`203`	`203`	`}`
`204`	`204`
`205`	`205`	`if ($code >= 400 && $code < 500) {`
`206`		`- throw APIStatusError::from(request: $req, response: $rsp);`
	`206`	`+ throw APIStatusException::from(request: $req, response: $rsp);`
`207`	`207`	`}`
`208`	`208`
`209`	`209`	`if ($code >= 500 && $retryCount < $opts->maxRetries) {`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`use Scrapegraphai\Client;`
`8`	`8`	`use Scrapegraphai\Core\Conversion\Contracts\Converter;`
`9`	`9`	`use Scrapegraphai\Core\Conversion\Contracts\ConverterSource;`
`10`		`-use Scrapegraphai\Core\Errors\APIStatusError;`
	`10`	`+use Scrapegraphai\Core\Exceptions\APIStatusException;`
`11`	`11`	`use Scrapegraphai\RequestOptions;`
`12`	`12`
`13`	`13`	`/**`
`@@ -52,7 +52,7 @@ public function hasNextPage(): bool`
`52`	`52`	`*`
`53`	`53`	`* @return static of static<Item>`
`54`	`54`	`*`
`55`		`- * @throws APIStatusError`
	`55`	`+ * @throws APIStatusException`
`56`	`56`	`*/`
`57`	`57`	`public function getNextPage(): static`
`58`	`58`	`{`