Error handling
Cast has two different kinds of trouble. The server answered with an error — that is a response, and you can read it. There is no answer at all — that is an exception.
An error status is a response
PSR-18 requires a client to throw only when there is no response. A 404 or a 500 is a response:
$response = $client->get('users/999')->send();
if ($response->getStatusCode() === 404) {
return null;
}When an error status should stop execution, there are two ways.
On the call — throw() returns the same response or throws:
$user = $client->get('users/42')->send()->throw()->json();For the whole client — with withThrowOnError(), every send() throws on 4xx/5xx:
$strict = $client->withThrowOnError();
$strict->get('users/42')->send(); // HttpException on 4xx/5xxsendRequest() — the PSR-18 method — never throws on a status, even with withThrowOnError().
That way a third-party PSR-18 consumer gets the behaviour it expects.
What to catch
use Flytachi\Winter\Cast\Exception\ClientErrorException;
use Flytachi\Winter\Cast\Exception\NetworkException;
use Flytachi\Winter\Cast\Exception\ServerErrorException;
use Flytachi\Winter\Cast\Exception\TimeoutException;
try {
$report = $client->get('reports/2026')->send()->throw()->json();
} catch (ClientErrorException $e) { // 4xx — the request is wrong, retrying won't help
$problem = $e->getResponse()->json();
} catch (ServerErrorException $e) { // 5xx — the server failed
$status = $e->getStatusCode();
} catch (TimeoutException $e) { // gave up waiting
$e->isConnect(); // could not even connect
} catch (NetworkException $e) { // no connection: DNS, refused, dropped, TLS
$e->isTransient(); // a retry may help
}TimeoutException extends NetworkException, so it is caught first.
| Situation | Exception |
|---|---|
| invalid header, URI or method; JSON cannot be encoded; a reserved cURL option | InvalidArgumentException — while building the request |
address not http/https, no base URL, too many redirects |
RequestException — before sending |
| DNS, connection refused, TLS, dropped connection | NetworkException |
| a timeout or the deadline expired | TimeoutException |
body over maxResponseSize |
TooLargeException |
| 4xx / 5xx | a response; ClientErrorException / ServerErrorException with throw() |
sendAll(): some requests got no response |
BatchException — after all have finished |
All exceptions implement Psr\Http\Client\ClientExceptionInterface, so
catch (ClientExceptionInterface) catches any client error. The full hierarchy is in
Exceptions.
Messages without secrets
Exception messages carry the address without the query and without user:password@: keys in
the address do not end up in logs or in the error tracker. The request with all its data is
available through $e->getRequest().
A response that is not JSON
$data = $response->json(); // null if not a JSON object or array
$data = $response->jsonOrFail(); // CastException with the status and Content-TypeA common case: the load balancer returned an HTML 502 page. json() gives null, and
jsonOrFail() gives a clear message: “Expected a JSON object or array in the response
(HTTP 502, text/html)”.
Retry instead of failing
Transient failures — connection refused, a dropped connection, a timeout, a 503 — often pass on the second attempt. Turn on retries, and only the final error reaches your code: see Timeouts and retries.