Error Handling

Circuit breaker, retries, failOpen mode, and timeout handling.

The PlatformXe SDK includes built-in resilience features to handle transient failures gracefully.

Retry with exponential backoff

Transient failures (5xx errors, network timeouts) are automatically retried with exponential backoff and jitter.

const px = new PlatformXeClient({
  apiKey: process.env.PLATFORMXE_API_KEY!,
  retries: 3,      // Up to 3 retry attempts
  timeoutMs: 10000, // 10 second timeout per attempt
});

Retry delays follow this pattern:

Attempt	Base delay	With jitter
1	200ms	150–250ms
2	400ms	300–500ms
3	800ms	600–1000ms

Client errors (4xx) are not retried — they indicate invalid requests that will fail again.

failOpen mode

When failOpen is true, the SDK returns an error envelope instead of throwing an exception. This is critical for permission checks where a network failure should not crash your application.

const px = new PlatformXeClient({
  apiKey: process.env.PLATFORMXE_API_KEY!,
  failOpen: true,
});

const result = await px.permissions.check({
  adminId: 'user_xyz789',
  path: 'articles',
  action: 'read',
});

if (!result.success) {
  // PlatformXe unreachable — fall back to default policy
  console.error('Permission check failed:', result.error.message);
  return defaultPolicy(path, action);
}

return result.data.allowed;

Error envelope format

interface ErrorResponse {
  success: false;
  error: {
    code: string;    // e.g., "NETWORK_ERROR", "TIMEOUT", "RATE_LIMITED"
    message: string; // Human-readable description
  };
}

Circuit breaker

The SDK implements a circuit breaker that opens after consecutive failures, preventing cascading timeout delays.

State	Behavior
Closed	Requests flow normally
Open	Requests fail immediately (returns error envelope if failOpen)
Half-open	One probe request sent — if it succeeds, circuit closes

The circuit opens after 5 consecutive failures and resets after 30 seconds.

Timeout handling

If a request exceeds timeoutMs, it is aborted. If retries remain, the SDK retries. Otherwise:

• failOpen: true — returns { success: false, error: { code: 'TIMEOUT' } }
• failOpen: false — throws a TimeoutError

try {
  const result = await px.permissions.check({
    adminId: 'user_xyz789',
    path: 'articles',
    action: 'read',
  });
} catch (err) {
  if (err.code === 'TIMEOUT') {
    // All retries timed out
    return fallbackDecision();
  }
  throw err;
}

Error codes

Code	Description
NETWORK_ERROR	Could not connect to PlatformXe
TIMEOUT	Request timed out after all retries
RATE_LIMITED	Rate limit exceeded (check Retry-After header)
BAD_REQUEST	Invalid request parameters
FORBIDDEN	API key missing required scope
NOT_FOUND	Resource does not exist
CIRCUIT_OPEN	Circuit breaker is open