Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Setting a longer (or shorter) timeout for Laravel's Http client

ErrorIlluminate\Http\Client\ConnectionException

Short answer

The Laravel Http client waits 30 seconds for a response and 10 seconds to connect. A slower API throws a ConnectionException. Call timeout() with more seconds, and connectTimeout() if the connection itself is slow. Add retry() for flaky endpoints. Raise the limits only as far as the job or request that runs the call can wait.

  • Applies to Laravel 12, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the exception message. It says whether the wait for the response or the connection step ran out of time.

    try {
        Http::get('https://api.example.com/report');
    } catch (\Illuminate\Http\Client\ConnectionException $e) {
        logger()->error($e->getMessage());
    }
  2. 2Match what you see, then jump to its fix

    1. 1ConnectionException after about 30 seconds, while the same URL works in a browserThe response takes longer than the default 30 secondsFix
    2. 2The exception comes quickly (near 10 seconds) and no response was receivedThe connection step is the slow partFix
    3. 3The same request works when repeatedA flaky endpoint fails once and the code gives upFix

What does the error look like?

  • Illuminate\Http\Client\ConnectionException
  • Request takes 30 seconds, then fails

Cause 1 of 3

The response takes longer than the default 30 seconds

1Check

By default the client times out after 30 seconds of waiting for the response. Measure how long the API needs.

$start = microtime(true);
Http::timeout(120)->get('https://api.example.com/report');
echo round(microtime(true) - $start, 1).' seconds';

2Fix

Set a longer timeout for that request only, in seconds.

$response = Http::timeout(120)->get('https://api.example.com/report');

3Verify

Run the call again and confirm it returns a response.

echo Http::timeout(120)->get('https://api.example.com/report')->status();

Confirmed by laravel.com

Did this fix it?

Cause 2 of 3

The connection step is the slow part

1Check

connectTimeout is the time allowed to connect to the server, 10 seconds by default. A server that is down or unreachable fails here, and a longer timeout() does not help.

// a short connect limit shows quickly whether the connection step is the problem
Http::connectTimeout(2)->get('https://api.example.com/report');

2Fix

If the connect time is genuinely slow, raise connectTimeout. If the host is unreachable, fix the network or DNS instead of waiting longer.

$response = Http::connectTimeout(20)->timeout(60)->get('https://api.example.com/report');

3Verify

Repeat the request and check that a status code comes back.

echo Http::connectTimeout(20)->timeout(60)->get('https://api.example.com/report')->status();

Confirmed by laravel.com

Did this fix it?

Cause 3 of 3

A flaky endpoint fails once and the code gives up

1Check

A single transient failure is thrown as a ConnectionException with no second attempt.

grep -rn "Http::" app/ | head

2Fix

Use retry() with a count and a pause in milliseconds. The third argument limits retries to connection errors, so a 4xx from the API is not repeated.

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\PendingRequest;
use Throwable;

$response = Http::timeout(30)
    ->retry(3, 200, function (Throwable $e, PendingRequest $request) {
        return $e instanceof ConnectionException;
    })
    ->get('https://api.example.com/report');

3Verify

Point the call at a URL that fails once, and check the response arrives on a later attempt.

echo $response->status();

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Set timeout() on every call to a third-party API, so one slow service cannot hold a request for 30 seconds.
  • Move calls that need more than a few seconds into a queued job.
  • Catch ConnectionException where the call is made and return a clear message or a fallback.
  • Keep the timeout lower than the limit of whatever runs the code (web server, PHP, or queue worker).

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.