Laravel HTTP Client Retry: Only Retry Failures That Matter

The Laravel HTTP client retry feature is easy to switch on and easy to misuse. Http::retry(3, 100) retries on almost any failure, including a 404 that will never succeed and a 422 validation error that will fail identically every time. Each wasted attempt adds latency and load to someone else's API. retry() has two lesser-known arguments that fix this: a callback that decides whether a failure is worth retrying, and a throw flag that controls what you get back when every attempt fails.

The default: retry everything

use Illuminate\Support\Facades\Http;

$response = Http::retry(3, 100)->post('https://api.example.com/orders', $payload);

The first argument is the maximum number of attempts and the second is the wait between them in milliseconds. If the request fails with a client or server error, Laravel tries again. That is fine for a flaky network and wrong for a request that is simply invalid.

Decide what to retry with the third argument

Per the Laravel documentation, the third argument is a callable that determines whether the retries should actually be attempted. It receives the exception and the pending request. Return true to retry and false to stop.

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

$response = Http::retry(3, 200, function (Throwable $exception, PendingRequest $request) {
    // Network problems: worth another try.
    if ($exception instanceof ConnectionException) {
        return true;
    }

    // Server errors (5xx): the other side may recover.
    if ($exception instanceof RequestException) {
        return $exception->response->serverError();
    }

    return false;
})->post('https://api.example.com/orders', $payload);

With this callback, a connection failure or a 5xx is retried up to three attempts. A 404 or a 422 is not retried at all. The callback returns false and the client stops immediately.

For 429, retrying immediately usually makes things worse. If you do retry it, make the delay meaningful. The second argument can be a closure that receives the attempt number and returns the milliseconds to wait, such as fn (int $attempt) => $attempt * 500, and you can also pass an array of delays as the first argument, as in Http::retry([100, 200, 400]).

Get the last response back with throw: false

By default, when all attempts fail, Laravel throws a RequestException. If you would rather inspect the final response yourself, pass throw: false:

$response = Http::retry(3, 200, $shouldRetry, throw: false)
    ->post('https://api.example.com/orders', $payload);

if ($response->failed()) {
    // $response is the last response received, e.g. the 422 with its error body.
    logger()->warning('Order sync failed', [
        'status' => $response->status(),
        'body'   => $response->json(),
    ]);
}

This is especially useful with the callback above. A 422 is not retried, and instead of an exception you get the response and can read the validation errors from the body.

The catch: connection failures still throw

The documentation is explicit about one limit: if all of the requests fail because of a connection issue, a ConnectionException is still thrown even when throw is false. There is no response to return in that case, so throw: false only covers failures that came back as an HTTP response. If you want to handle both, wrap the call:

try {
    $response = Http::retry(3, 200, $shouldRetry, throw: false)->post($url, $payload);
} catch (ConnectionException $e) {
    // The service was unreachable on every attempt.
    $response = null;
}

Check it with a fake

You can prove the callback works without calling a real API. This test feeds a 422 and expects exactly one request, because a 422 must not be retried:

use Illuminate\Support\Facades\Http;

Http::fake([
    'api.example.com/*' => Http::sequence()
        ->push(['error' => 'invalid'], 422)
        ->push(['ok' => true], 200),
]);

$response = Http::retry(3, 0, $shouldRetry, throw: false)
    ->post('https://api.example.com/orders', ['sku' => 'A1']);

expect($response->status())->toBe(422);
Http::assertSentCount(1);

Swap the first pushed response for a 503 and the same test should report two requests and a 200. (The test above uses Pest's expect(); in PHPUnit use $this->assertSame(422, $response->status()).)

Production considerations

• Be careful retrying POST. A request that timed out may still have been processed on the other side. Retrying a payment or order creation can duplicate it unless the API supports an idempotency key, which you would send as a header with withHeaders().
• Retrying multiplies load. Three attempts across 1,000 queued jobs can mean 3,000 calls to a service that is already struggling. Keep attempts low and delays non-zero.
• Inside queued jobs, think twice. The job's own $tries and backoff may already retry the whole job, so layering HTTP retries on top multiplies attempts.

• Set a timeout. Retries on a request that hangs for the default timeout can stall a worker for a long time. Add ->timeout(5) to bound each attempt.

   

References: Laravel HTTP Client: Retries and Laravel HTTP Client: Testing.