Add custom exceptions for error handling

.gitignore

@@ -10,3 +10,4 @@ vendor
 .php-cs-fixer.cache
 .phpunit.cache
 composer.lock
+test-request.php

AGENTS.md

@@ -16,13 +16,27 @@ composer require phpjuice/wati-http-client
 use Wati\Http\WatiClient;
 use Wati\Http\WatiEnvironment;
 
-$endpoint = 'https://your-instance.wati.io';
+// Get this URL from your Wati Dashboard (API Docs section)
+// It includes your tenant ID: https://your-instance.wati.io/{tenantId}
+$endpoint = 'https://your-instance.wati.io/123456';
 $bearerToken = 'your-bearer-token';
 
 $environment = new WatiEnvironment($endpoint, $bearerToken);
 $client = new WatiClient($environment);
 ```
 
+#### With Custom Options
+
+```php
+$client = new WatiClient($environment, [
+    'timeout' => 60,           // Request timeout in seconds (default: 30)
+    'connect_timeout' => 15,   // Connection timeout in seconds (default: 10)
+    'verify' => true,          // Verify SSL certificate (default: true)
+    'proxy' => 'tcp://localhost:8080',  // Proxy URL (default: null)
+    'debug' => false,          // Enable debug mode (default: false)
+]);
+```
+
 ### 3. Make API Requests
 
 Extend `WatiRequest` to create requests:
@@ -65,7 +79,45 @@ composer types
 src/
 ├── WatiClient.php       # Main HTTP client
 ├── WatiEnvironment.php  # Holds endpoint + token
-└── WatiRequest.php      # Base request class
+├── WatiRequest.php      # Base request class
+└── Exceptions/
+    ├── WatiException.php          # Base exception
+    ├── WatiApiException.php       # API error responses
+    ├── AuthenticationException.php # 401 errors
+    ├── RateLimitException.php     # 429 errors
+    └── ValidationException.php    # 400/422 errors
+```
+
+## Error Handling
+
+The client throws specific exceptions for different error scenarios:
+
+```php
+use Wati\Http\Exceptions\AuthenticationException;
+use Wati\Http\Exceptions\RateLimitException;
+use Wati\Http\Exceptions\ValidationException;
+use Wati\Http\Exceptions\WatiApiException;
+use Wati\Http\Exceptions\WatiException;
+
+try {
+    $response = $client->send(new GetContactsRequest());
+} catch (AuthenticationException $e) {
+    // Invalid bearer token - check credentials
+    echo "Auth failed: " . $e->getMessage();
+} catch (RateLimitException $e) {
+    // Rate limited - wait and retry
+    $retryAfter = $e->getRetryAfter(); // seconds to wait
+} catch (ValidationException $e) {
+    // Invalid request parameters
+    $errors = $e->getResponseData();
+} catch (WatiApiException $e) {
+    // Other API errors (4xx, 5xx)
+    $statusCode = $e->getStatusCode();
+    $data = $e->getResponseData();
+} catch (WatiException $e) {
+    // Connection or other HTTP errors
+    echo "Request failed: " . $e->getMessage();
+}
 ```
 
 ## Common Operations

README.md

@@ -6,7 +6,8 @@
 [![Total Downloads](http://poser.pugx.org/phpjuice/wati-http-client/downloads)](https://packagist.org/packages/phpjuice/wati-http-client)
 [![License](http://poser.pugx.org/phpjuice/wati-http-client/license)](https://packagist.org/packages/phpjuice/wati-http-client)
 
-A PHP HTTP Client for the [Wati.io](https://wati.io) WhatsApp API. Provides a simple, fluent API to interact with Wati's REST API.
+A PHP HTTP Client for the [Wati.io](https://wati.io) WhatsApp API. Provides a simple, fluent API to interact with Wati's
+REST API.
 
 ## Installation
 
@@ -32,8 +33,9 @@ composer require "phpjuice/wati-http-client"
 use Wati\Http\WatiClient;
 use Wati\Http\WatiEnvironment;
 
-// Your API endpoint and bearer token from the Wati dashboard
-$endpoint = "https://your-instance.wati.io";
+// Get this URL from your Wati Dashboard (API Docs section)
+// It includes your tenant ID: https://your-instance.wati.io/{tenantId}
+$endpoint = "https://your-instance.wati.io/123456";
 $bearerToken = "your-bearer-token";
 
 // Create environment
@@ -43,6 +45,20 @@ $environment = new WatiEnvironment($endpoint, $bearerToken);
 $client = new WatiClient($environment);
 ```
 
+#### With Custom Options
+
+```php
+<?php
+
+$client = new WatiClient($environment, [
+    'timeout' => 60,           // Request timeout in seconds (default: 30)
+    'connect_timeout' => 15,   // Connection timeout in seconds (default: 10)
+    'verify' => true,          // Verify SSL certificate (default: true)
+    'proxy' => 'tcp://localhost:8080',  // Proxy URL (default: null)
+    'debug' => false,          // Enable debug mode (default: false)
+]);
+```
+
 ## Usage
 
 ### Making Requests
@@ -121,6 +137,40 @@ For full API documentation, visit [Wati API Docs](https://docs.wati.io/reference
 - **Templates**: Get and send message templates
 - **Campaigns**: Manage broadcasts
 
+## Error Handling
+
+The client throws specific exceptions for different error scenarios:
+
+```php
+<?php
+
+use Wati\Http\Exceptions\AuthenticationException;
+use Wati\Http\Exceptions\RateLimitException;
+use Wati\Http\Exceptions\ValidationException;
+use Wati\Http\Exceptions\WatiApiException;
+use Wati\Http\Exceptions\WatiException;
+
+try {
+    $response = $client->send(new GetContactsRequest());
+} catch (AuthenticationException $e) {
+    // Invalid bearer token - check credentials
+    echo "Auth failed: " . $e->getMessage();
+} catch (RateLimitException $e) {
+    // Rate limited - wait and retry
+    $retryAfter = $e->getRetryAfter(); // seconds to wait
+} catch (ValidationException $e) {
+    // Invalid request parameters
+    $errors = $e->getResponseData();
+} catch (WatiApiException $e) {
+    // Other API errors (4xx, 5xx)
+    $statusCode = $e->getStatusCode();
+    $data = $e->getResponseData();
+} catch (WatiException $e) {
+    // Connection or other HTTP errors
+    echo "Request failed: " . $e->getMessage();
+}
+```
+
 ## Changelog
 
 Please see the [CHANGELOG](changelog.md) for more information on what has changed recently.

changelog.md

@@ -2,6 +2,18 @@
 
 All notable changes to `phpjuice/wati-http-client` will be documented in this file.
 
+## 1.0.1 - 2026-02-20
+
+- Custom exceptions for error handling:
+    - `WatiException` - Base exception
+    - `WatiApiException` - API error responses with status code and response data
+    - `AuthenticationException` - 401 errors
+    - `RateLimitException` - 429 errors with retry-after support
+    - `ValidationException` - 400/422 errors
+- Configurable HTTP options (timeout, connect_timeout, verify, proxy, debug)
+- Proper tenant ID handling in URLs with trailing slash preservation
+- Request path normalization for correct URI resolution with base URLs containing paths
+
 ## 1.0.0 - 2026-02-20
 
 - Initial release of Wati HTTP Client (PHP 8.3+ support)

phpunit.xml

@@ -3,6 +3,7 @@
          xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
          bootstrap="vendor/autoload.php"
          colors="true"
+         cacheDirectory=".phpunit.cache"
 >
     <testsuites>
         <testsuite name="Unit">

src/Exceptions/AuthenticationException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wati\Http\Exceptions;
+
+use Psr\Http\Message\ResponseInterface;
+use Throwable;
+
+class AuthenticationException extends WatiApiException
+{
+    public function __construct(
+        string $message = 'Authentication failed. Check your bearer token.',
+        ?ResponseInterface $response = null,
+        ?Throwable $previous = null
+    ) {
+        parent::__construct($message, 401, $response, $previous);
+    }
+}

src/Exceptions/RateLimitException.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wati\Http\Exceptions;
+
+use Psr\Http\Message\ResponseInterface;
+use Throwable;
+
+class RateLimitException extends WatiApiException
+{
+    protected ?int $retryAfter = null;
+
+    public function __construct(
+        string $message = 'Rate limit exceeded. Please retry after some time.',
+        ?ResponseInterface $response = null,
+        ?Throwable $previous = null
+    ) {
+        parent::__construct($message, 429, $response, $previous);
+
+        if ($response instanceof ResponseInterface) {
+            $retryAfter = $response->getHeaderLine('Retry-After');
+            $this->retryAfter = $retryAfter !== '' ? (int) $retryAfter : null;
+        }
+    }
+
+    public function getRetryAfter(): ?int
+    {
+        return $this->retryAfter;
+    }
+}

src/Exceptions/ValidationException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wati\Http\Exceptions;
+
+use Psr\Http\Message\ResponseInterface;
+use Throwable;
+
+class ValidationException extends WatiApiException
+{
+    public function __construct(
+        string $message = 'Validation failed. Check your request parameters.',
+        ?ResponseInterface $response = null,
+        ?Throwable $previous = null
+    ) {
+        parent::__construct($message, 400, $response, $previous);
+    }
+}

src/Exceptions/WatiApiException.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wati\Http\Exceptions;
+
+use Psr\Http\Message\ResponseInterface;
+use Throwable;
+
+class WatiApiException extends WatiException
+{
+    /** @var array<mixed>|null */
+    protected ?array $responseData = null;
+
+    public function __construct(
+        string $message,
+        protected int $statusCode,
+        ?ResponseInterface $response = null,
+        ?Throwable $previous = null
+    ) {
+        if ($response instanceof ResponseInterface) {
+            $body = $response->getBody()->getContents();
+            $decoded = json_decode($body, true);
+            $this->responseData = is_array($decoded) ? $decoded : null;
+        }
+
+        parent::__construct($message, $statusCode, $previous);
+    }
+
+    public function getStatusCode(): int
+    {
+        return $this->statusCode;
+    }
+
+    /** @return array<mixed>|null */
+    public function getResponseData(): ?array
+    {
+        return $this->responseData;
+    }
+}

src/Exceptions/WatiException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wati\Http\Exceptions;
+
+use Exception;
+
+class WatiException extends Exception {}