WestyxNexus\Exceptions\NexusException, which extends \RuntimeException. Catch the base class to handle every SDK error in one place, or a subclass for fine-grained control. Your HTTP client’s own exception types never reach your code: a network failure arrives as a NexusException with the client’s exception as getPrevious().
Exception hierarchy
An invalid
NexusConfig value is an \InvalidArgumentException, thrown by the constructor - see Configuration.
One mapping, every endpoint
/v1/sync, /v1/flags/evaluate-ab, the three secret-write endpoints, the stream and the token exchange share one status-to-exception mapping, so the same server response produces the same exception whichever call made it:
Imports
Catching exceptions at client creation
Branching on an API error
Handling rate limits
Handling quarantine
Reading a secret with a public key
402 Payment Required
A402 is raised wherever it arrives - from create(), sync(), a write, and from a read whose TTL has elapsed - because a suspended account is a condition the application has to see. The snapshot is never cleared, and nothing latches: the first sync after the invoice is settled succeeds normally.
A switched-off environment
While the environment is switched off, a read keeps serving the cached snapshot and does not throw: the refresh is attempted once every five minutes, one warning is logged, and the first successful sync clears it.create(), an explicit sync(), evaluateAb() and the write methods throw NexusEnvironmentDisabledException. The stream waits five minutes between attempts - see SSE live updates.
What is not thrown
- A refresh that fails for a transient reason - a read after the TTL logs
nexus: refresh failed, serving the cached snapshotaterrorand serves the last snapshot. Rejected credentials, a suspended account, a missing service and an unrenewable WIF session are raised instead. - A WIF refresh that fails while the session is still valid - logged at
warning; the request goes out with the current session. - A missing config or flag -
getConfigreturns$default(ornull);getFlagreturns$default. - A missing secret -
getSecretandgetSecretFilePathreturnnull. 304 Not Modified- a successful sync; the TTL restarts.- Stream failures inside
connectStream()- logged and retried with backoff, then the polling fallback; the call ends by throwing on a rejected key (401), a suspended account (402), or a locked-down service (423 service_locked).
The asymmetry between secrets (
null) and configs and flags (the default) is deliberate: a missing secret usually means misconfiguration, while a missing flag almost always means “use the safe default and continue”.Network down at startup
If the backend is unreachable whencreate() runs, the PSR-18 client raises a Psr\Http\Client\ClientExceptionInterface, which the SDK wraps in a NexusException - one exception type whichever client is in use:
