Error Handling - Law4Devs

Exception Hierarchy

All SDK exceptions extend Law4Devs\Exceptions\Law4DevsException, which itself extends \RuntimeException.

\RuntimeException
└── Law4DevsException          base — any SDK error
    ├── NotFoundError          404 — resource not found
    ├── ValidationError        400 — invalid parameters
    ├── RateLimitError         429 — rate limit exceeded
    └── ServerError            5xx — server-side error

Every exception exposes a statusCode property:

try {
    $article = $client->articles->get('gdpr', 9999);
} catch (\Law4Devs\Exceptions\NotFoundError $e) {
    echo 'Not found: ' . $e->getMessage() . "\n";  // message from API
    echo 'Status: ' . $e->statusCode . "\n";        // 404
}

Catching Specific Errors

use Law4Devs\Exceptions\Law4DevsException;
use Law4Devs\Exceptions\NotFoundError;
use Law4Devs\Exceptions\RateLimitError;
use Law4Devs\Exceptions\ValidationError;

try {
    $page = $client->articles->list('invalid-framework');
} catch (NotFoundError $e) {
    // Framework not found
    echo 'Framework not found: ' . $e->getMessage() . "\n";
} catch (ValidationError $e) {
    // Bad request parameters
    echo 'Invalid request: ' . $e->getMessage() . "\n";
} catch (RateLimitError $e) {
    // Retry after a delay (SDK already retried 3 times)
    echo 'Rate limit hit: ' . $e->getMessage() . "\n";
} catch (Law4DevsException $e) {
    // All other SDK errors (server errors, network failures)
    echo 'SDK error (' . $e->statusCode . '): ' . $e->getMessage() . "\n";
}

Automatic Retry

The SDK automatically retries on 429 Too Many Requests and 5xx Server Error responses using exponential backoff:

Attempt	Wait
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds

After maxRetries (default 3) attempts, the exception is re-thrown. To disable retries, set maxRetries: 0:

$client = new \Law4Devs\Client(
    apiKey:     getenv('LAW4DEVS_API_KEY'),
    maxRetries: 0,
);

Network Errors

Connection failures (timeout, DNS, SSL) throw Law4DevsException with statusCode of null:

use Law4Devs\Exceptions\Law4DevsException;

try {
    $page = $client->frameworks->list();
} catch (Law4DevsException $e) {
    if ($e->statusCode === null) {
        echo 'Network error: ' . $e->getMessage() . "\n";
    }
}

Best Practices

Always catch Law4DevsException as a fallback to handle unexpected errors
Check $e->statusCode to distinguish network errors (null) from API errors
Wrap iter() loops in a try/catch — exceptions can occur mid-iteration if a page request fails
For batch processing, implement a retry strategy at the application level if you need finer control than the built-in retry