---
title: "Exceptions — Plausible for Laravel | Roundly"
description: "The PlausibleException hierarchy — configuration, visitor, revenue, unsupported-request and rate-limit errors — and how HTTP failures surface."
url: https://roundly-consulting.com/open-source/docs/plausible-for-laravel/exceptions
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Plausible for Laravel](https://roundly-consulting.com/open-source/docs/plausible-for-laravel.md)

# Exceptions

Every exception the package throws extends RoundlyConsulting\\Plausible\\Exceptions\\PlausibleException, so one catch handles anything from the client:

| Exception | Thrown when |
| --- | --- |
| `MissingConfiguration` | url is missing on the first call, key is missing on the first Stats or Sites call (event capture works without one), a call needs a site and none was passed nor configured, or a breakdown, cursor() or each() has no property. |
| `UnsupportedRequest` | The target endpoint can’t do what was asked — allTime() on a v1 terminal, a minute, hour or week interval on v1 timeseries(), or a site update with a timezone or without a new domain. Thrown before anything is sent. |
| `UniqueVisitorIdentifierRequired` | An event is captured (sync, queued or batched) before setVisitor() or fromRequest(). |
| `InvalidRevenue` | A revenue currency or amount is invalid — the money exception is chained as getPrevious(). |
| `RateLimitExceeded` | A throttled request would wait longer than the surface’s max\_wait. Carries key and retryAfterSeconds(). |

```php
use Illuminate\Http\Client\RequestException;
use RoundlyConsulting\Plausible\Enums\Metric;
use RoundlyConsulting\Plausible\Exceptions\PlausibleException;

try {
    $visitors = Plausible::stats()->query()->last7Days()->aggregate()->metric(Metric::Visitors);
} catch (PlausibleException $e) {
    // configuration, visitor, revenue, unsupported-request or rate-limit problem raised by the package
} catch (RequestException $e) {
    // Plausible answered with a non-2xx status — $e->response holds it
}
```

A malformed setting is the one exception from outside this hierarchy: it throws RoundlyConsulting\\PackageToolkit\\Exceptions\\InvalidConfigurationException from the package toolkit, naming the key — an env typo such as PLAUSIBLE\_TIMEOUT=five or PLAUSIBLE\_STATS\_RATELIMIT\_PER=hourly. See Configuration.

## HTTP failures

HTTP errors are Laravel’s own: a non-2xx response from Plausible throws Illuminate\\Http\\Client\\RequestException — after the rate limiter has recorded any 429 penalty — and a network failure throws Illuminate\\Http\\Client\\ConnectionException. Enable retry.\* for transient failures — a failed connection or a 5xx.

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/plausible-for-laravel.md)