Package · cast

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:

php
$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:

php
$user = $client->get('users/42')->send()->throw()->json();

For the whole client — with withThrowOnError(), every send() throws on 4xx/5xx:

php
$strict = $client->withThrowOnError();
$strict->get('users/42')->send();   // HttpException on 4xx/5xx

sendRequest() — 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

php
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

php
$data = $response->json();          // null if not a JSON object or array
$data = $response->jsonOrFail();    // CastException with the status and Content-Type

A 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.