Skip to content

Handling Client Errors in Guzzle

When a PHP request through Guzzle returns a 4xx status, the library raises an exception instead of returning a normal response.

OUTPUT FORMATSHTMLJSONMarkdown

Catching the right exception lets you inspect the status and body, log the failure, and decide whether to retry, fall back, or stop.

Catch the exception around the request

Wrap the Guzzle call in a try block. If the server answers with a client error, Guzzle throws an exception that you can catch and handle instead of letting the request fail unhandled. The choice of exception type controls how narrowly you respond.

Use a project with Guzzle installed. Set COMPOSER_AUTOLOAD to its Composer autoloader path and TARGET_URL to the URL you want to request. A 4xx response enters the ClientException handler.

<?php
require getenv('COMPOSER_AUTOLOAD');
use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;

$http = new Client();
try {
    $result = $http->get(getenv('TARGET_URL'));
    echo $result->getStatusCode() . PHP_EOL;
} catch (ClientException $failure) {
    $result = $failure->getResponse();
    echo $result->getStatusCode() . PHP_EOL;
    echo $result->getBody()->getContents();
}

Choose broad or narrow coverage

Catch RequestException for broader coverage of most Guzzle exceptions. Catch ClientException when you want to isolate client errors, such as 4xx status codes, and treat them differently from other failures. This distinction matters when a 404 should trigger a fallback while a connection problem should follow a different recovery path.

Inspect the response attached to the exception

The protected example in module code0001 requests a 404 endpoint inside a try block and catches ClientException. Inside the handler, it obtains the response attached to the exception, reads the body as a string, and outputs the status code. That pattern gives you the evidence needed to log the failure or build a recovery response. Refer to protected module code0001 for the exact implementation.

Recovery checklist

Before shipping the handler, check that the exception type matches the failures you intend to handle, that the status code is logged, that the body is read safely, and that the recovery path does not silently swallow unexpected errors. For the full list of exception types, consult the Guzzle exception reference linked below.

Which exception should you catch?
Exception to catchBest useWhat it covers
RequestExceptionOne handler for most failuresMost exceptions thrown by Guzzle
ClientExceptionSeparate handling for client errorsClient exceptions such as 4xx status codes

Based on the exception descriptions in the supplied material; consult the linked Guzzle exception reference for the complete list.

Frequently asked questions

Should I catch RequestException or ClientException?

Use RequestException when you want one handler to cover most Guzzle failures, or ClientException when you only want to handle client-side 4xx responses separately from other failures.

Can I still inspect the response body after a client error?

Yes. In the protected example, the exception carries the HTTP response, so you can retrieve its status code and read the body as a string for logging or recovery.

What does the 404 example demonstrate?

A 404 is the worked example: the request is placed in a try block, ClientException is caught, and the handler prints the 404 status code from the attached response.