Skip to main content
All SDK exceptions extend 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

A 402 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 snapshot at error and 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 - getConfig returns $default (or null); getFlag returns $default.
  • A missing secret - getSecret and getSecretFilePath return null.
  • 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 when create() 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: