How to Set Timeouts and Retry Failed Requests with the Laravel HTTP Client

When Laravel sends a request to an external API, the server may respond slowly or the connection may fail. Set a timeout to limit how long Laravel waits for a response. Set a retry policy to send the request again after selected failures.

You can use timeout() and retry() together on a Laravel HTTP request. The timeout applies to each attempt. The retry settings determine which failures trigger another attempt and how long Laravel waits between attempts.

Set a timeout for each request

Call timeout() before the HTTP method to set the maximum wait, in seconds, for each request. Store the value in your service configuration and choose a limit that fits the API and your code’s response-time requirements:

use Illuminate\Support\Facades\Http;

$response = Http::timeout(config('services.partner.timeout_seconds'))
    ->get($endpoint);

Set services.partner.timeout_seconds in your configuration to a number of seconds. If Laravel does not receive a response before that time, the request fails with a connection exception.

A per-request timeout does not limit the total time for the operation. Each attempt has its own timeout, and the delays between attempts add to the total. Choose the timeout and retry limit based on how long the caller can wait. Laravel’s HTTP client examples show timeout configuration alongside other request options.

Retry only the failures worth repeating

Use retry() to set the attempt limit and the delay between attempts. A callback chooses which failures trigger another request. For example, retry a temporary network failure or server-side error. A client error, such as an invalid request, usually needs a code or data fix.

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

$response = Http::timeout(config('services.partner.timeout_seconds'))
    ->retry(3, 100, function (
        Throwable $exception,
        PendingRequest $request
    ): bool {
        if ($exception instanceof ConnectionException) {
            return true;
        }

        return $exception instanceof RequestException
            && $exception->response->serverError();
    })
    ->get($endpoint);

Here, 3 sets the attempt limit, and 100 sets the pause between attempts in milliseconds. The callback retries connection failures and responses with server-error status codes. Laravel Daily’s retry examples also show how to retry selected status codes, including 429, which means the server is limiting requests. Add a check for that status to the callback to retry it.

By default, Laravel’s HTTP client does not throw an exception for every unsuccessful HTTP status. A retry callback lets you choose which failures justify another attempt instead of treating every unsuccessful response the same way.

Consider duplicate effects before retrying

A timeout does not prove that the remote server failed to act. The server may have completed the request but failed to return a response before Laravel’s timeout expired. If Laravel retries a request that creates a payment, order, or other one-time effect, the server may perform the action twice.

For requests that cause side effects, use the API’s idempotency mechanism if it provides one. An idempotency key tells the server that repeated requests represent the same intended operation. If the API does not support idempotency, retry only when the failure gives you a sound reason to believe the server did not complete the action.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com