An SMS provider outage makes a Laravel 13 app report thousands of identical exceptions a minute; how do you throttle that reporting with withExceptions()?

## The problem: a flood of identical reports When an external dependency such as an SMS gateway goes down, every request or queued job that calls it throws the same exception. Each one is reported: written to the log and forwarded to any error tracker hooked into the handler. Thousands of identical entries a minute fill disks, cost money on paid tracking plans and bury the one different error you need to see. Laravel's exception handler can **throttle reporting** without touching how the failure is handled or rendered. ## Registering a throttle callback In `bootstrap/app.php`, `$exceptions->throttle(callable $throttleUsing)` registers a closure. Like report callbacks, it is matched by its **first-parameter type-hint**, and it returns one of three things for the exception it receives: | Return value | Effect | |---|---| | `Lottery::odds(1, 1000)` | Random sampling: each occurrence is reported with a 1-in-1000 chance | | `Limit::perMinute(300)` | Rate limit: up to 300 reports per window, the rest dropped | | `Limit::perMinute(300)->by($key)` | Same, counted under your own key | | `null` | No opinion: the next throttle callback is asked, and if none answers, the exception is unthrottled | | `Limit::none()` | Explicitly unthrottled | `Lottery` is `Illuminate\Support\Lottery`; `Limit` is `Illuminate\Cache\RateLimiting\Limit`, the same class route rate limiters use, so `perSecond()`, `perHour()` and `perDay()` work too. ## How a Limit is counted For a `Limit`, the handler calls `RateLimiter::attempt()` with: 1. a key: the value of `->by()` if set, otherwise `illuminate:foundation:exceptions:` plus the exception's class name, then hashed with `xxh128`; 2. the limit's maximum attempts and its decay window in seconds. When the window's budget is used up, `attempt()` returns `false` and the exception is treated as "should not report". The `RateLimiter` stores its counters in the **cache**: the default store, or the one named by the `limiter` key in `config/cache.php`. That has consequences: - With a shared store such as Redis or the database, the budget is shared by every web server and queue worker. - With a per-machine store such as `file`, each machine has its own budget. - The whole throttle decision runs inside `rescue()` with reporting disabled, and a failure there means "report". If the cache store throws, for example because the database behind the skeleton's `database` cache store is the thing that is down, the handler **fails open** and reports unthrottled. ## Where throttling sits in the pipeline Throttling is the last of the "should this be reported?" checks, after deduplication, `ShouldntReport`, the `dontReport` lists and `dontReportWhen`. A dropped exception therefore never reaches: - its own `report()` method, - any report callback registered with `$exceptions->report()`, - the default logger. Anything that listens on those paths, including error-tracking integrations, sees only what passed the throttle. Nothing records how many were dropped, so if you need the true failure rate, count it somewhere the throttle does not sit in front of, such as a metric incremented where the SMS call fails. ## Choosing keys and numbers - Keep keys **bounded**. `->by($e->getMessage())` is fine for a fixed message, but a message that embeds a phone number or message id gives every failure its own budget and throttles nothing. - Key by the dimension you want visibility on, such as the provider name, so an outage of one gateway does not use up the budget of another. - Prefer `Limit` for outage floods, since you are guaranteed the first reports of each window, and `Lottery` for steady high-volume noise, where a sample is enough. - Leave everything else unthrottled by returning `null` for types you do not recognise. - Remember the window: a `Limit` starts counting at the first report and, once the budget is spent, drops everything until the decay window expires; then a fresh budget begins. A `perMinute(30)` therefore gives you a burst of 30 at the top of each window, not one report every two seconds. ## What throttling does not do Throttling changes what is **recorded**, not what **happens**. The user still gets the same error response, the job still fails or retries, and the gateway is still being hammered. Pair it with handling the outage itself: short HTTP timeouts, moving SMS sending into queued jobs with backoff, and a fallback provider. Lowering the exception's level with `level()` so it does not page anyone is another complementary step.