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.
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.
| Exception to catch | Best use | What it covers |
|---|---|---|
| RequestException | One handler for most failures | Most exceptions thrown by Guzzle |
| ClientException | Separate handling for client errors | Client 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.