A Laravel job that geocodes imported property listings uses the RateLimited job middleware, and during a large import many jobs land in failed_jobs with MaxAttemptsExceededException although handle() never threw — why, and how do you fix it?

## The symptom A property-listing import dispatches one `GeocodeListing` job per listing. The geocoding API allows a fixed number of calls per minute, so the job carries the built-in `Illuminate\Queue\Middleware\RateLimited` middleware with a named limiter: ```php public function middleware(): array { return [new RateLimited('geocoding')]; } ``` On a small import everything works. On a large one, hundreds of jobs appear in `failed_jobs` with `MaxAttemptsExceededException` and the message "has been attempted too many times", yet `handle()` never threw and the geocoding API never returned an error. ## Why a release fails the job `RateLimited` runs **before** `handle()`. When the limiter is exhausted it does not wait; it **releases** the job back onto the queue with a delay equal to the time until the limiter frees up (or the value given to `releaseAfter()`). The problem is the attempt count: 1. The worker picks the job up: attempt 1. The limiter is full, so the middleware releases it. 2. After the delay a worker picks it up again: attempt 2. 3. Before running anything, the worker compares attempts with the job's `tries`. The job sets none, so the worker's `--tries` default of **1** applies, and 2 exceeds it. 4. The job is failed with `MaxAttemptsExceededException` and written to `failed_jobs`. The Laravel docs warn about exactly this: releasing a rate-limited job still increments its attempts, and by default a job is attempted only once. ## Options that do not fix it | Idea | Why it falls short | |---|---| | Raise `--tries` on the worker | Changes every job on that worker, and a fixed count still runs out on a long enough backlog | | `->dontRelease()` | Rate-limited jobs are dropped without running, so listings silently stay without coordinates | | A huge `#[Tries(1000)]` alone | Also allows 1000 runs of a job that throws on every attempt | | Catching the limit inside `handle()` | Rebuilds the middleware and still releases, so attempts still climb | ## The fix: a deadline plus an exception cap Give the job a **time budget** instead of a count, and cap genuine errors separately: ```php #[MaxExceptions(3)] class GeocodeListing implements ShouldQueue { use Queueable; public function middleware(): array { return [(new RateLimited('geocoding'))->releaseAfter(30)]; } public function retryUntil(): DateTime { return now()->addHours(6); } } ``` - `retryUntil()` makes the worker ignore `tries`: releases can happen as often as needed until the deadline. - `#[MaxExceptions(3)]` fails the job after three **unhandled exceptions**, so a broken address format or an API outage does not loop for six hours. Releases by the middleware are not exceptions and do not count toward it. - `releaseAfter(30)` spaces the retries evenly instead of relying only on the limiter's reset time. ## Sizing the deadline `retryUntil()` is evaluated **at dispatch** and stored in the payload, so the clock starts when the import queues the job, not when a worker first touches it. If 30,000 listings are queued at once and the API allows 100 calls a minute, the last job cannot run for about five hours; a one-hour deadline would fail the tail of the import with the same `MaxAttemptsExceededException`. Size the deadline from **backlog divided by allowed rate**, with margin, or dispatch in smaller waves. ## What a long deadline costs A generous `retryUntil()` is not free, so keep an eye on the side effects: - **Queue depth.** Released jobs go back onto the same queue, so thousands of waiting geocoding jobs sit alongside other work. Dispatching them to a dedicated queue keeps a slow import from delaying password-reset mail. - **Churn.** Without `releaseAfter()`, each over-limit job is released for exactly the time until the limiter frees, and the whole backlog wakes at once to compete for the next window. A fixed delay spreads the pickups. - **Silent loss.** A deadline that is too short fails the tail of the import; one that is too long hides a stuck import for hours. Alert on `failed_jobs` growth for this job class either way. ## Confirming the diagnosis - `php artisan queue:failed` lists the failed jobs by ID, class and time; the `exception` column of their `failed_jobs` rows shows `MaxAttemptsExceededException` rather than an API error. - After deploying the fix, `php artisan queue:retry all` pushes them back with a fresh attempt count and a recomputed deadline.