Error handling

Failed requests throw RoundlyConsulting\KubernetesApi\Exceptions\KubernetesException. It extends Laravel’s RequestException — catch (RequestException), $e->response and $e->getCode() (the HTTP status) keep working — and adds accessors that read the apiserver’s Status from the body on demand:

use RoundlyConsulting\KubernetesApi\Exceptions\KubernetesException;

try {
    $cluster->secrets()->setNamespace('shop')->setName('db')->create();
} catch (KubernetesException $e) {
    $e->status();       // 409 (also $e->getCode())
    $e->reason();       // 'AlreadyExists' — only a well-formed reason token, else null
    $e->apiMessage();   // 'secrets "db" already exists', or null
    $e->details();      // the Status details array (name, kind, causes…), or []
    $e->getMessage();   // 'secrets "db" already exists' — never the raw body
    $e->response;       // the full Laravel Response, body included
}

Messages never carry the body

Exception messages end up in logs and failed_jobs, so they never include the raw response body — an edge HTML page, or a proxy that echoes the Authorization header, would otherwise put the bearer token there. Laravel’s own body summary, which its handler writes into the message on report(), is never used:

• The generic message adds the Status reason when the body has a well-formed one.
• A redirect that wasn’t followed reads Kubernetes API request was redirected (HTTP 302 to https://login.example:8443) and the redirect was not followed — the target’s origin only, never its path or query.
• A success answer the call can’t use throws KubernetesException::malformedResponse(): Malformed TokenRequest response from the Kubernetes API (HTTP 201).
• new KubernetesException($response, ?string $message = null, bool $redacted = false) uses a message of your own as given.

Redacted errors

withRedactedErrors() — or redact_errors on a cluster’s config entry — cuts messages to status and reason, leaving out even the Status message. The accessors and $e->response still read the body, because asking for it is a choice, and applyConfig() keeps the setting:

$cluster = Kubernetes::cluster('production')->withRedactedErrors();
// or 'redact_errors' => true on the cluster's config entry (KUBERNETES_REDACT_ERRORS)

try {
    $cluster->secrets()->setNamespace('shop')->setName('db')->create();
} catch (KubernetesException $e) {
    $e->getMessage();   // 'HTTP 409 AlreadyExists'
    $e->apiMessage();   // still 'secrets "db" already exists' — reading it is a choice
}

Service-account token requests are always redacted, whatever the cluster says — it is a credential endpoint. A refused exec upgrade throws WebSocketException with the status line plus the apiserver’s Status message (the status line only when the cluster redacts), such as WebSocket upgrade failed: HTTP/1.1 403 Forbidden: pods "api" is forbidden; response headers and body are never included.

Every exception

A 404 from find() is the usual signal to create — existsOnCluster() and updateOrCreate() already handle it for you. A 409 from update() or updateOrCreate() means the object changed since you read it: re-read and retry.