PHP SDK - Error Handling

All SDK exceptions extend WestyxNexus\Exceptions\NexusException which itself extends \RuntimeException. This means you can catch the base class to handle any SDK error, or catch specific subclasses for fine-grained control.

Exception hierarchy

Exception	Extends	HTTP status	When thrown
`NexusException`	`\RuntimeException`	-	Base class; not thrown directly
`NexusUnauthorizedException`	`NexusException`	401	Invalid API key, slug/key mismatch, or revoked key
`NexusBillingException`	`NexusException`	402	Tenant has overdue invoices (>14 days)
`NexusNotFoundException`	`NexusException`	404	Unknown subdomain or missing endpoint
`NexusPublicKeyException`	`NexusException`	-	public key used with `getSecret`, `getSecretFilePath`, or write methods; thrown before any network call
`NexusAbAddonNotAvailableException`	`NexusException`	403	`evaluateAb` on a project without the AB Testing add-on. Its own type because retrying is pointless - the add-on stays absent until it is activated
`NexusRateLimitedException`	`NexusException`	429	Rate limit exceeded; has `$retryAfterSeconds` property (nullable int)
`NexusQuarantinedException`	`NexusException`	429 (quarantine body)	Service quarantined; has `$reason` (string) and `$expiresAt` (string, server-supplied timestamp) properties
`NexusSessionExpiredException`	`NexusException`	-	A WIF session expired and could not be refreshed. The SDK fails closed: while WIF is active there is no API-key fallback. Carries the underlying failure as `getPrevious()`
`NexusDeveloperCredentialsException`	`NexusSessionExpiredException`	-	The `developer` provider found no usable credential for this endpoint. The message names the service and the `westyx dev setup` command that renews it
`NexusTokenSourceException`	`NexusException`	-	A configured `WifCredentialSource` raised. Distinct from an expired session on purpose: the fault is in application code, not the backend refusing a credential. The original is `getPrevious()`

Imports

use WestyxNexus\Exceptions\NexusException;
use WestyxNexus\Exceptions\NexusUnauthorizedException;
use WestyxNexus\Exceptions\NexusBillingException;
use WestyxNexus\Exceptions\NexusNotFoundException;
use WestyxNexus\Exceptions\NexusPublicKeyException;
use WestyxNexus\Exceptions\NexusRateLimitedException;
use WestyxNexus\Exceptions\NexusQuarantinedException;

Catching exceptions

Basic pattern

try {
    $client = NexusClient::create(new NexusConfig(
        baseUrl: $_ENV['NEXUS_URL'],
        apiKey:  $_ENV['NEXUS_API_KEY'],
    ));
} catch (NexusUnauthorizedException $e) {
    // Bad API key or slug/key mismatch
    error_log('nexus: unauthorized - ' . $e->getMessage());
    exit(1);
} catch (NexusBillingException $e) {
    // Tenant has overdue invoices
    error_log('nexus: billing overdue - ' . $e->getMessage());
    exit(1);
} catch (NexusException $e) {
    // Any other SDK error (network failure, 404, etc.)
    error_log('nexus: init failed - ' . $e->getMessage());
    exit(1);
}

Handling rate limits

NexusRateLimitedException carries an optional $retryAfterSeconds property parsed from the Retry-After response header:

try {
    $client->sync();
} catch (NexusRateLimitedException $e) {
    $wait = $e->retryAfterSeconds;
    if ($wait !== null) {
        sleep($wait);
        $client->sync(); // retry
    } else {
        error_log('nexus: rate limited - ' . $e->getMessage());
    }
}

Handling quarantine

NexusQuarantinedException is thrown when the backend returns a 429 with a quarantine body. The service is blocked until the quarantine expires:

try {
    $client->sync();
} catch (NexusQuarantinedException $e) {
    error_log(sprintf(
        'nexus: quarantined until %s - reason: %s',
        $e->expiresAt,
        $e->reason,
    ));
    // Cache continues to be served; schedule a retry after $e->expiresAt
}

Reading a secret with a public key

NexusPublicKeyException fires synchronously before any network call:

try {
    $value = $client->getSecret('DB_PASSWORD');
} catch (NexusPublicKeyException $e) {
    // The client was created with a public key
    error_log('nexus: public keys cannot read secrets - use a secret key');
}

402 Payment Required - `NexusBillingException`

When the backend returns HTTP 402 (the tenant has at least one invoice overdue by more than 14 days), the SDK:

Throws NexusBillingException from NexusClient::create or sync().
Halts the background sync loop - read methods continue to serve the last cached snapshot (or the empty cache if billing was overdue on first connect).

The cache stays valid and readable until the process ends. The billing block clears automatically when a subsequent sync() succeeds after the invoice is settled.

try {
    $client->sync();
} catch (NexusBillingException $e) {
    // Log a warning and continue serving the cached values
    $logger->warning('nexus: billing overdue - config refresh suspended; cache may be stale');
}

The snapshot is never cleared, but a 402 is raised rather than served from cache: a suspended account is a condition the application has to see. Reads raise NexusBillingException until billing is resolved, at which point the next sync succeeds normally - nothing latches.

What is NOT thrown as an exception

TTL-triggered syncs - a transient failure is retried and the last known snapshot is served, logged as nexus: refresh failed, serving the cached snapshot at error level. Rejected credentials, a suspended account, a missing service and an unrenewable WIF session are raised instead.
Missing config or flag - getConfig returns $default (or null); getFlag returns $default.
304 Not Modified - treated as success; TTL reset.
SSE transport errors inside connectStream() - logged and counted toward $maxErrors; method returns normally when the limit is reached.

The asymmetry between secrets (return null) and configs/flags (return default) is deliberate: a missing secret often means misconfiguration, while a missing flag almost always means “use the safe default and continue”.

Failure scenarios

Wrong API key

try {
    $client = NexusClient::create(new NexusConfig(
        baseUrl: $_ENV['NEXUS_URL'],
        apiKey:  'invalid_key',
    ));
} catch (NexusUnauthorizedException $e) {
    die('nexus: bad API key or slug mismatch');
}

Network down at startup

If the Nexus backend is unreachable when NexusClient::create runs, the PSR-18 client raises a Psr\Http\Client\ClientExceptionInterface, which the SDK wraps in a NexusException - so you catch one exception type whichever client is in use:

try {
    $client = NexusClient::create($config);
} catch (NexusException $e) {
    // Log and decide: crash or retry with backoff
    error_log('nexus: ' . $e->getMessage());
    exit(1);
}

Reading a secret that doesn’t exist

$value = $client->getSecret('does.not.exist');
// $value is null - no exception thrown

if ($value === null) {
    error_log('nexus: secret not found - using default');
    $value = 'default-value';
}

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

PHP SDK - Error Handling

Exception hierarchy

Imports

Catching exceptions

Basic pattern

Handling rate limits

Handling quarantine

Reading a secret with a public key

402 Payment Required - `NexusBillingException`

What is NOT thrown as an exception

Failure scenarios

Wrong API key

Network down at startup

Reading a secret that doesn’t exist

​Exception hierarchy

​Imports

​Catching exceptions

​Basic pattern

​Handling rate limits

​Handling quarantine

​Reading a secret with a public key

​402 Payment Required - NexusBillingException

​What is NOT thrown as an exception

​Failure scenarios

​Wrong API key

​Network down at startup

​Reading a secret that doesn’t exist

Exception hierarchy

Imports

Catching exceptions

Basic pattern

Handling rate limits

Handling quarantine

Reading a secret with a public key

402 Payment Required - `NexusBillingException`

What is NOT thrown as an exception

Failure scenarios

Wrong API key

Network down at startup

Reading a secret that doesn’t exist