feat!: rename errors to exceptions

stainless-app[bot] · stainless-app[bot] · commit 8bbf53adda49 · 2025-08-27T00:19:34.000Z
diff --git a/README.md b/README.md
@@ -110,12 +110,12 @@ foreach ($page->pagingEachItem() as $item) {
 
 ### 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 `Anthropic\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 `Anthropic\Core\Exceptions\APIException` will be thrown:
 
 ```php
 <?php
 
-use Anthropic\Core\Errors\APIConnectionError;
+use Anthropic\Core\Exceptions\APIConnectionException;
 use Anthropic\Messages\MessageParam;
 
 try {
@@ -124,7 +124,7 @@ try {
     messages: [MessageParam::with(role: "user", content: "Hello, Claude")],
     model: "claude-sonnet-4-20250514",
   );
-} catch (APIConnectionError $e) {
+} catch (APIConnectionException $e) {
   echo "The server could not be reached", PHP_EOL;
   var_dump($e->getPrevious());
 } catch (RateLimitError $_) {
@@ -137,19 +137,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
@@ -8,7 +8,7 @@
 use Anthropic\Core\Contracts\BaseStream;
 use Anthropic\Core\Conversion\Contracts\Converter;
 use Anthropic\Core\Conversion\Contracts\ConverterSource;
-use Anthropic\Core\Errors\APIStatusError;
+use Anthropic\Core\Exceptions\APIStatusException;
 use Anthropic\RequestOptions;
 use Http\Discovery\Psr17FactoryDiscovery;
 use Http\Discovery\Psr18ClientDiscovery;
@@ -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 Anthropic\Client;
 use Anthropic\Core\Conversion\Contracts\Converter;
 use Anthropic\Core\Conversion\Contracts\ConverterSource;
-use Anthropic\Core\Errors\APIStatusError;
+use Anthropic\Core\Exceptions\APIStatusException;
 use Anthropic\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 Anthropic\Core\Errors;
+namespace Anthropic\Core\Exceptions;
 
-class APIConnectionError extends APIError
+class APIConnectionException extends APIException
 {
     /** @var string */
     protected const DESC = 'Anthropic API Connection Error';
diff --git a/src/Core/Exceptions/APIException.php b/src/Core/Exceptions/APIException.php
@@ -1,11 +1,11 @@
 <?php
 
-namespace Anthropic\Core\Errors;
+namespace Anthropic\Core\Exceptions;
 
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
-class APIError extends AnthropicError
+class APIException extends AnthropicException
 {
     public ?int $status = null;
 
diff --git a/src/Core/Exceptions/APIStatusException.php b/src/Core/Exceptions/APIStatusException.php
@@ -1,12 +1,12 @@
 <?php
 
-namespace Anthropic\Core\Errors;
+namespace Anthropic\Core\Exceptions;
 
 use Anthropic\Core\Util;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
-class APIStatusError extends APIError
+class APIStatusException extends APIException
 {
     /** @var string */
     protected const DESC = 'Anthropic 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 Anthropic\Core\Errors;
+namespace Anthropic\Core\Exceptions;
 
 use Psr\Http\Message\RequestInterface;
 
-class APITimeoutError extends APIConnectionError
+class APITimeoutException extends APIConnectionException
 {
     /** @var string */
-    protected const DESC = 'Anthropic API Timeout Error';
+    protected const DESC = 'Anthropic API Timeout Exception';
 
     public function __construct(
         public RequestInterface $request,
diff --git a/src/Core/Exceptions/AnthropicException.php b/src/Core/Exceptions/AnthropicException.php
@@ -1,8 +1,8 @@
 <?php
 
-namespace Anthropic\Core\Errors;
+namespace Anthropic\Core\Exceptions;
 
-class AnthropicError extends \Exception
+class AnthropicException extends \Exception
 {
     /** @var string */
     protected const DESC = 'Anthropic Error';
diff --git a/src/Core/Exceptions/AuthenticationException.php b/src/Core/Exceptions/AuthenticationException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class AuthenticationException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Authentication Exception';
+}
diff --git a/src/Core/Exceptions/BadRequestException.php b/src/Core/Exceptions/BadRequestException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class BadRequestException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Bad Request Exception';
+}
diff --git a/src/Core/Exceptions/ConflictException.php b/src/Core/Exceptions/ConflictException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class ConflictException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Conflict Exception';
+}
diff --git a/src/Core/Exceptions/InternalServerException.php b/src/Core/Exceptions/InternalServerException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class InternalServerException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Internal Server Exception';
+}
diff --git a/src/Core/Exceptions/NotFoundException.php b/src/Core/Exceptions/NotFoundException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class NotFoundException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Not Found Exception';
+}
diff --git a/src/Core/Exceptions/PermissionDeniedException.php b/src/Core/Exceptions/PermissionDeniedException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class PermissionDeniedException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Permission Denied Exception';
+}
diff --git a/src/Core/Exceptions/RateLimitException.php b/src/Core/Exceptions/RateLimitException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class RateLimitException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Rate Limit Exception';
+}
diff --git a/src/Core/Exceptions/UnprocessableEntityException.php b/src/Core/Exceptions/UnprocessableEntityException.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Anthropic\Core\Exceptions;
+
+class UnprocessableEntityException extends APIStatusException
+{
+    /** @var string */
+    protected const DESC = 'Anthropic Unprocessable Entity Exception';
+}
diff --git a/src/Core/SSEStream.php b/src/Core/SSEStream.php
@@ -4,7 +4,7 @@
 
 use Anthropic\Core\Concerns\SdkStream;
 use Anthropic\Core\Contracts\BaseStream;
-use Anthropic\Core\Errors\APIStatusError;
+use Anthropic\Core\Exceptions\APIStatusException;
 
 /**
  * @template TItem
@@ -53,7 +53,7 @@ private function parsedGenerator(): \Generator
                         $json = Util::decodeJson($chunk['data']);
                         $message = Util::prettyEncodeJson($json);
 
-                        $exn = APIStatusError::from(
+                        $exn = APIStatusException::from(
                             request: $this->request,
                             response: $this->response,
                             message: $message,

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`use Anthropic\Client;`
`8`	`8`	`use Anthropic\Core\Conversion\Contracts\Converter;`
`9`	`9`	`use Anthropic\Core\Conversion\Contracts\ConverterSource;`
`10`		`-use Anthropic\Core\Errors\APIStatusError;`
	`10`	`+use Anthropic\Core\Exceptions\APIStatusException;`
`11`	`11`	`use Anthropic\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`	`{`