Skip to content

PHP cURL and Guzzle Proxy: Setup and Proxy Error Handling

The proxy options in PHP cURL and Guzzle, safe timeouts, and a way to tell whether a failure comes from the proxy or from the target site.

The same proxy in cURL and in Guzzle

The same proxy in cURL and in Guzzle
ItemPHP cURLGuzzle
Proxy address and protocolCURLOPT_PROXY with a scheme: http://HOST:2222 or socks5h://HOST:3333'proxy' => the same string; it is copied to CURLOPT_PROXY
Login and passwordCURLOPT_PROXYUSERPWD => 'USERNAME:PASSWORD'In the proxy URL, or in 'curl' => [CURLOPT_PROXYUSERPWD => ...]
Connect timeoutCURLOPT_CONNECTTIMEOUT, default 300 seconds'connect_timeout', default 0 = wait indefinitely
Total timeoutCURLOPT_TIMEOUT, default 0 = no limit'timeout', default 0 = wait indefinitely

Source: PHP manual cURL constants, libcurl CURLOPT_PROXY page and Guzzle request options, read on 17 November 2026. The Guzzle page does not mention SOCKS5; with the cURL handler the string goes straight to libcurl.

PHP cURL: proxy, timeouts and error codes

The example sets the proxy with its scheme, the login with CURLOPT_PROXYUSERPWD, and both timeouts. Passing the login separately means you do not have to percent-encode special characters in the password; the libcurl page we read does not say whether credentials inside the proxy string are decoded. Use socks5h:// when the proxy should resolve the target’s name too.

After curl_exec() read three things: curl_errno() (0 means cURL had no error), CURLINFO_HTTP_CODE (the answer of the target site) and CURLINFO_HTTP_CONNECTCODE (the proxy’s answer to CONNECT). Together they say whether the failure is the proxy or the site.

PHP cURL example with error classification

<?php
// PHP cURL extension. Save as check.php and run: php check.php

function fetchViaProxy(string $url, string $proxy, string $userpwd): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_PROXY          => $proxy,     // 'http://HOST:2222' or 'socks5h://HOST:3333'
        CURLOPT_PROXYUSERPWD   => $userpwd,   // 'USERNAME:PASSWORD'
        CURLOPT_CONNECTTIMEOUT => 10,         // PHP default is 300 seconds
        CURLOPT_TIMEOUT        => 30,         // PHP default is 0 = no limit
    ]);
    $body = curl_exec($ch);

    return [
        'body'        => $body,
        'errno'       => curl_errno($ch),                           // 0 = no cURL error
        'error'       => curl_error($ch),
        'http'        => curl_getinfo($ch, CURLINFO_HTTP_CODE),     // answer of the target site
        'connectCode' => curl_getinfo($ch, CURLINFO_HTTP_CONNECTCODE), // answer of the proxy to CONNECT
        'seconds'     => curl_getinfo($ch, CURLINFO_TOTAL_TIME),
    ];
}

function explain(array $r): string
{
    switch ($r['errno']) {
        case 0:   return $r['http'] >= 400 ? "target answered HTTP {$r['http']}" : 'ok';
        case 5:   return 'proxy host name cannot be resolved: check HOST';
        case 7:   return 'cannot open a connection to the proxy or the target: check HOST, PORT, firewall';
        case 28:  return 'timeout: proxy or target too slow, or wrong port';
        case 35:  return 'TLS handshake failed';
        case 52:
        case 56:  return 'connection closed or nothing received: check the protocol matches the port';
        case 97:  return 'proxy handshake failed (SOCKS): check protocol, username and password';
        default:  return "cURL error {$r['errno']}: {$r['error']}";
    }
}

$r = fetchViaProxy('https://ipinfo.io/json', 'http://HOST:2222', 'USERNAME:PASSWORD');
echo explain($r), PHP_EOL;
if ($r['connectCode'] === 407) {
    echo 'The proxy answered CONNECT with 407: check username, password and the IP term', PHP_EOL;
}
echo $r['body'], PHP_EOL;

Replace HOST, USERNAME and PASSWORD with the values from My assets, and use the port that matches the protocol. Error texts follow the libcurl error-code page.

What the cURL error numbers say about the proxy

What the cURL error numbers say about the proxy
ItemMeaning in libcurlWhat to check first
5Could not resolve the proxy hostHOST spelling, DNS of the machine
7Could not open a connection to the target or the proxyHOST and PORT, firewall, protocol matches the port
28The time limit was reachedPort, a slow target, or a timeout that is too short
35TLS handshake failedThe target’s certificate, or something that intercepts HTTPS on the machine
52, 55, 56Nothing returned, send failure, receive failureThe scheme in CURLOPT_PROXY must match the port: http for 2222, socks5h for 3333
97The proxy handshake failedProtocol, username, password; PHP 8.2 and newer can add detail with CURLINFO_PROXY_ERROR

Source: libcurl error-code page and PHP manual constants, read on 17 November 2026. The check column is our reading of those descriptions.

Guzzle: the proxy option and two exception classes

Guzzle’s documented proxy option takes a string for all protocols or an array for http, https and a no list. Guzzle fills NO_PROXY from the environment only when you do not pass your own proxy option. The documentation does not mention SOCKS5, but its source copies the string to CURLOPT_PROXY, so with the cURL handler a socks5h:// address is passed to libcurl as is.

For errors, Guzzle’s source creates ConnectException only for cURL errors 28, 6, 7, 35 and 52. Everything else, such as 5 (proxy host), 56 (receive) and 97 (proxy handshake), arrives as RequestException with no response. A 4xx or 5xx from the target is also a RequestException (ClientException or ServerException) unless you set http_errors to false.

Guzzle example with both exception classes

<?php
// composer require guzzlehttp/guzzle
// Load Composer's autoload.php here (require the file Composer created in your project).

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ConnectException;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'proxy'           => 'http://HOST:2222',       // or 'socks5h://HOST:3333' for an IP bought as SOCKS5
    'curl'            => [CURLOPT_PROXYUSERPWD => 'USERNAME:PASSWORD'],
    'connect_timeout' => 10,                        // Guzzle default is 0 = wait indefinitely
    'timeout'         => 30,                        // Guzzle default is 0 = wait indefinitely
]);

try {
    $response = $client->request('GET', 'https://ipinfo.io/json');
    echo $response->getBody(), PHP_EOL;
} catch (ConnectException $e) {
    // Guzzle's cURL handler uses this class for errno 6, 7, 28, 35 and 52
    $errno = $e->getHandlerContext()['errno'] ?? '?';
    echo "Connection problem (errno $errno): ", $e->getMessage(), PHP_EOL;
} catch (RequestException $e) {
    if ($e->hasResponse()) {
        echo 'HTTP ', $e->getResponse()->getStatusCode(), PHP_EOL;     // 4xx or 5xx from the target
    } else {
        // other cURL errors, for example 5 (proxy host), 56 (receive) or 97 (proxy handshake)
        $errno = $e->getHandlerContext()['errno'] ?? '?';
        echo "No response (errno $errno): ", $e->getMessage(), PHP_EOL;
    }
}

Replace HOST, USERNAME and PASSWORD with the values from My assets. The comments about errno numbers follow the Guzzle 7.9 source.

Quick fixes

The script hangs for minutes

Check Are both timeouts set? PHP’s connect timeout defaults to 300 seconds and the total timeout to 0, and Guzzle’s two defaults wait indefinitely.

Fix Set CURLOPT_CONNECTTIMEOUT and CURLOPT_TIMEOUT, or connect_timeout and timeout.

errno 7, or 56 right after connecting

Check Does the scheme match the port? An IP bought as HTTP answers on 2222, an IP bought as SOCKS5 on 3333.

Fix Copy HOST, PORT and the protocol again from My assets, then run curl -x with the same values.

connectCode 407, or errno 97

Check Username, password and the IP’s end date.

Fix Copy the details again and test them with curl. See the proxy authentication guide for the 407 answer.

Stop when If curl with the same details also fails, the problem is the proxy details, not PHP.

HTTP 403 or 429 and errno 0

Check The proxy worked: cURL had no error and the answer came from the target site.

Fix Read the site’s rules and slow your request rate. This is not a proxy fault.

With Proxy302: steps

  1. Step 1

    Pick the product on the automation page. A datacenter IP costs US$0.25 for 1 day or US$3.99 for 30 days, the same in every country; rotating residential is billed per GB. There is no free trial.

  2. Step 2

    Open My assets and copy HOST, PORT, USERNAME and PASSWORD. A leased IP has one protocol, chosen at purchase: HTTP on port 2222 or SOCKS5 on port 3333.

  3. Step 3

    Run the cURL example, then the Guzzle one. Read ipinfo.io’s answer: the IP and country must be the proxy’s.

    Expected result JSON with the proxy’s IP, and no error text.

FAQ

How do I set a proxy with login and password in PHP cURL?

Set CURLOPT_PROXY to the address with its scheme and CURLOPT_PROXYUSERPWD to USERNAME:PASSWORD, as the PHP manual describes.

Does Guzzle support SOCKS5 proxies?

The documentation does not mention it. In the source the proxy string is copied to CURLOPT_PROXY, and libcurl accepts socks5:// and socks5h://, so with the cURL handler it works as a string. Confirm with the ipinfo.io request.

How do I tell a proxy error from a target-site error?

If curl_errno() is not 0, the request did not complete: 5, 7 and 97 point at the proxy, 28 is a timeout. If it is 0 and CURLINFO_HTTP_CODE is 4xx or 5xx, the proxy worked and the site answered with that code.

Why does my script wait so long when the proxy is down?

PHP’s connect timeout defaults to 300 seconds, its total timeout to 0 (no limit), and Guzzle’s defaults wait indefinitely. Set both timeouts.

Can I try Proxy302 for free from PHP?

There is no free trial. The smallest purchases are 1 GB of rotating residential traffic or one IP for one day.

Reference links

8
  1. libcurl: CURLOPT_PROXY

    Official documentation · Confirmed on:

    Read on 17 November 2026: accepted scheme prefixes http://, https://, socks4://, socks4a://, socks5:// and socks5h:// (socks5h lets the proxy resolve the host name); port 1080 if none is given; user and password can be written in the string or set with CURLOPT_PROXYUSERNAME and CURLOPT_PROXYPASSWORD; the option overrides proxy environment variables; an empty string disables the proxy.

    The page does not say whether credentials in the string must be percent-encoded.

  2. libcurl: error codes

    Official documentation · Confirmed on:

    Read on 17 November 2026: 5 could not resolve the proxy host, 6 could not resolve the target host, 7 could not open a connection to the target or the proxy, 28 time limit reached, 35 TLS handshake failed, 52 nothing returned, 55 send failure, 56 receive failure, 97 proxy handshake failed (CURLINFO_PROXY_ERROR gives detail).

  3. PHP manual: cURL constants

    Official documentation · Confirmed on:

    Read on 17 November 2026: CURLOPT_PROXY, CURLOPT_PROXYUSERPWD ([username]:[password]), CURLOPT_PROXYTYPE (default CURLPROXY_HTTP), CURLOPT_CONNECTTIMEOUT (default 300 seconds, 0 waits indefinitely), CURLOPT_TIMEOUT (default 0, no limit during transfer), CURLINFO_HTTP_CONNECTCODE (the CONNECT response code), CURLINFO_PROXY_ERROR (PHP 8.2.0 and cURL 7.73.0).

  4. PHP manual: curl_errno and curl_getinfo

    Official documentation · Confirmed on:

    Read on 17 November 2026: curl_errno() returns the error number of the last operation or 0 if none; curl_error() returns the message; curl_getinfo() returns keys such as http_code, total_time, connect_time and primary_ip.

  5. Guzzle docs: Request options

    Official documentation · Confirmed on:

    Read on 17 November 2026: the proxy option takes a string for all protocols or an array with http, https and no keys; credentials can be written in the proxy URL; NO_PROXY is read automatically only when you do not pass your own proxy option; connect_timeout and timeout are floats whose default 0 waits indefinitely; http_errors is true by default and turns 4xx and 5xx into exceptions.

    The page does not mention SOCKS5.

  6. Guzzle docs: Exceptions

    Official documentation · Confirmed on:

    Read on 17 November 2026: TransferException is the base class; ConnectException is thrown on a networking error; RequestException is the parent of BadResponseException (ClientException for 4xx, ServerException for 5xx) and TooManyRedirectsException.

  7. Guzzle source: cURL handler (7.9)

    Official documentation · Confirmed on:

    Read on 17 November 2026: a string proxy option is copied to CURLOPT_PROXY; options in the curl array replace the handler’s cURL options; ConnectException is created only for cURL errors 28, 6, 7, 35 and 52, and every other cURL error (for example 5, 56 and 97) becomes RequestException.

  8. Proxy302 product facts and price list

    Product observation · Confirmed on:

    Product facts file of the site, checked 10 November 2026 against the console, the backend and the price table: datacenter per-IP lease US$0.25 for 1 day and US$3.99 for 30 days, the same in every country; HTTP port 2222 and SOCKS5 port 3333; one protocol per leased IP; rotating residential on proxy.proxy302.com with one login for both protocols; quantity up to 100 per order; no free trial.

Ready to try it?

Create an account, top up once, then pick rotating residential, static ISP or datacenter IPs and have one running in your browser within minutes.