Exception Classes

View Categories

Exception Classes

2 min read

The SDK throws typed exceptions for all error conditions. All exceptions extend ApiException.

Exception Hierarchy #

ApiException (base)
├── AuthenticationException  (HTTP 401)
├── RateLimitException       (HTTP 429)
├── ValidationException      (HTTP 422)
└── NotFoundException        (HTTP 404)

Non-4xx errors (e.g. 500 Internal Server Error) throw the base ApiException.

ApiException (Base Class) #

Namespace: DMSI\AdvancedApi\Exceptions\ApiException

Property / MethodDescription
getMessage()Human-readable error message from the API
getStatusCode(): intHTTP status code
getErrorCode(): stringMachine-readable error code (e.g. not_found)
getErrors(): arrayFull errors array from the API response

The static factory method ApiException::fromResponse() dispatches to the appropriate subtype based on HTTP status:

HTTP StatusException Class
401AuthenticationException
404NotFoundException
422ValidationException
429RateLimitException
Other 4xx / 5xxApiException

RateLimitException #

Adds a retryAfter property containing the value of the Retry-After header (seconds to wait before retrying).

use DMSI\AdvancedApi\Exceptions\RateLimitException;
try {
    $result = $client->licenses->list();
} catch (RateLimitException $e) {
    $wait = $e->retryAfter; // seconds
    sleep($wait);
    // retry
}

Note: The HttpClient retries 429 responses automatically up to 3 times. A RateLimitException is only thrown if all retries are exhausted.

ValidationException #

Thrown when the API returns HTTP 422. The getErrors() method returns the field-level validation error details.

use DMSI\AdvancedApi\Exceptions\ValidationException;
try {
    $client->licenses->create(['product_id' => 5]); // missing customer_id
} catch (ValidationException $e) {
    $fieldErrors = $e->getErrors();
    // ['customer_id' => ['This field is required.']]
}

Exception Handling Example #

use DMSI\AdvancedApi\Client;
use DMSI\AdvancedApi\Exceptions\ApiException;
use DMSI\AdvancedApi\Exceptions\AuthenticationException;
use DMSI\AdvancedApi\Exceptions\NotFoundException;
use DMSI\AdvancedApi\Exceptions\ValidationException;
use DMSI\AdvancedApi\Exceptions\RateLimitException;
$client = new Client('dmsi_key_...', 'https://yoursite.com');
try {
    $license = $client->licenses->get(999);
} catch (AuthenticationException $e) {
    // API key invalid, expired, or revoked
    error_log('Auth failed: ' . $e->getMessage());
} catch (NotFoundException $e) {
    // License ID 999 does not exist
    error_log('Not found: ' . $e->getMessage());
} catch (RateLimitException $e) {
    // All automatic retries exhausted
    error_log('Rate limited. Retry after: ' . $e->retryAfter . 's');
} catch (ValidationException $e) {
    // Invalid request data
    error_log('Validation errors: ' . json_encode($e->getErrors()));
} catch (ApiException $e) {
    // Any other API error
    error_log('API error [' . $e->getStatusCode() . ']: ' . $e->getMessage());
}

Part of the DMSI Advanced API v1.0.1 documentation set.
Cross-reference: For REST API endpoint details, see Part 5 – REST API Reference. For authentication methods, see Part 3 – Authentication. Note to publisher: update these cross-references to BetterDocs article slugs before publishing.

Leave a Reply