Should Http::retry() evaluate when on the final failed attempt?

[karim-tao]

Hi,

It looks like Http::retry() evaluates the when callback on the final failed attempt, even though there is no remaining attempt available.

Example:

use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;
use Throwable;

Http::fakeSequence()
    ->pushStatus(500)
    ->pushStatus(500)
    ->pushStatus(500);

$evaluations = 0;

try {
    Http::retry(
        times: [100, 200],
        when: function (Throwable $exception) use (&$evaluations) {
            $evaluations++;

            return true;
        },
    )->get('https://example.test');
} catch (RequestException) {
    echo $evaluations; // 3
}

With [100, 200], only two retries are possible, but when is evaluated three times.

This seems different from the global retry() helper, where the when callback is only evaluated after Laravel has determined that another attempt is still available.

From an API semantics perspective, I would expect Http::retry() to behave the same way: evaluate when only when another retry attempt is still available.

Is this behavior intentional? If so, I would be curious to understand the reasoning behind it.

[nirav-gajera]

Likely a bug. It's inconsistent with the global retry() helper, which only evaluates when if another attempt is available.

The Problem

With times: [100, 200] (2 retries), when gets called 3 times instead of 2. The final call is pointless—there's no retry to perform.

Why It Matters

• Confusing API: when suggests "decide if we should retry," not "observe every failure"
• Inconsistent: Global retry() helper doesn't behave this way
• Wasteful: Unnecessary callback evaluation on the final attempt

Quick Fix

Don't rely on when for side effects on the final attempt. Use catch instead:

try {
    Http::retry(times: [100, 200], when: $shouldRetry)->get($url);
} catch (RequestException $e) {
    // Handle final failure here
}

Recommendation

File an issue on the Laravel repository to clarify if intentional or fix it to match retry() behavior.