Error codes

Every error thrown by the SDK is an instance of ArlopassSDKError (or a subclass). Errors carry structured metadata for programmatic handling.

import {
  ArlopassSDKError,
  ArlopassStateError,
  ArlopassTransportError,
  ArlopassTimeoutError,
  ArlopassProtocolBoundaryError,
  ArlopassInvalidStateTransitionError,
} from "@arlopass/web-sdk";

Error hierarchy

// Error class hierarchy
ArlopassSDKError                          // Base class — all SDK errors extend this
├── ArlopassStateError                    // Invalid operation for current state
├── ArlopassInvalidStateTransitionError   // Illegal state transition
├── ArlopassProtocolBoundaryError         // Protocol envelope validation failure
├── ArlopassTransportError                // Transport-layer failure (retryable by default)
└── ArlopassTimeoutError                  // Request timed out (retryable by default)

Error properties

All error subclasses inherit these properties from ArlopassSDKError.

Prop	Type	Default	Description
`message`	`string`	—	Human-readable error description.
`machineCode`	`SDKMachineCode`	—	Stable machine-readable code for programmatic handling.
`reasonCode`	`ProtocolReasonCode`	—	Normalized reason code from the protocol layer.
`retryable`	`boolean`	—	Whether this error can be retried.
`correlationId`	`string \| undefined`	—	Correlation ID from the failed request.
`details`	`Record<string, string \| number \| boolean \| null> \| undefined`	—	Additional structured metadata about the error.
`cause`	`Error \| undefined`	—	Original error that caused this one.

SDK machine codes

Codes prefixed with ARLOPASS_SDK_ originate in the client SDK.

Prop	Type	Default	Description
`ARLOPASS_SDK_INVALID_STATE_TRANSITION`	`SDK`	—	Attempted an illegal state transition (e.g. connect while already connected).
`ARLOPASS_SDK_INVALID_STATE_OPERATION`	`SDK`	—	Operation not valid in the current state (e.g. chat.send while disconnected).
`ARLOPASS_SDK_MISSING_PROVIDER_SELECTION`	`SDK`	—	Chat operation attempted without selecting a provider first.
`ARLOPASS_SDK_PROTOCOL_VIOLATION`	`SDK`	—	Response envelope failed validation.
`ARLOPASS_SDK_TRANSPORT_ERROR`	`SDK`	—	Transport-level failure (network, serialization, etc.).

Protocol machine codes

Codes prefixed with ARLOPASS_ or ARLOPASS_PROTOCOL_ originate in the protocol layer or extension.

Prop	Type	Default	Description
`ARLOPASS_AUTH_FAILED`	`Protocol`	—	Authentication failure (invalid credentials).
`ARLOPASS_PERMISSION_DENIED`	`Protocol`	—	Caller lacks permission for the requested operation.
`ARLOPASS_TIMEOUT`	`Protocol`	—	Request timed out.
`ARLOPASS_PROVIDER_UNAVAILABLE`	`Protocol`	—	Selected provider is offline or unreachable.
`ARLOPASS_TRANSIENT_NETWORK`	`Protocol`	—	Transient network error.
`ARLOPASS_POLICY_VIOLATION`	`Protocol`	—	Request blocked by a policy rule.
`ARLOPASS_PROTOCOL_INVALID_ENVELOPE`	`Protocol`	—	Envelope structure is invalid.
`ARLOPASS_PROTOCOL_MISSING_REQUIRED_FIELD`	`Protocol`	—	A required field is missing from the envelope.
`ARLOPASS_PROTOCOL_ENVELOPE_EXPIRED`	`Protocol`	—	Envelope TTL has expired.
`ARLOPASS_PROTOCOL_REPLAY_PRONE_METADATA`	`Protocol`	—	Envelope metadata suggests a replay attack.
`ARLOPASS_PROTOCOL_UNSUPPORTED_VERSION`	`Protocol`	—	Protocol version not supported.
`ARLOPASS_PROTOCOL_UNSUPPORTED_CAPABILITY`	`Protocol`	—	Requested capability not supported.

Reason codes

Normalized reason codes provide a human-readable classification. The SDK normalizes aliases (e.g. "timeout" → "transport.timeout").

Prop	Type	Default	Description
`allow`	`Success`	—	Operation succeeded.
`auth.invalid`	`Auth`	—	Invalid credentials.
`auth.expired`	`Auth`	—	Credentials have expired.
`permission.denied`	`Auth`	—	Insufficient permissions.
`policy.denied`	`Policy`	—	Blocked by policy.
`provider.unavailable`	`Provider`	—	Provider is offline or unreachable.
`request.invalid`	`Request`	—	Malformed request.
`request.replay_prone`	`Request`	—	Request metadata suggests a replay.
`request.expired`	`Request`	—	Request envelope has expired.
`protocol.unsupported_version`	`Protocol`	—	Protocol version mismatch.
`protocol.unsupported_capability`	`Protocol`	—	Capability not recognized.
`protocol.invalid_envelope`	`Protocol`	—	Envelope validation failed.
`transport.timeout`	`Transport`	—	Operation timed out.
`transport.cancelled`	`Transport`	—	Operation was cancelled (e.g. AbortSignal).
`transport.transient_failure`	`Transport`	—	Temporary network or transport issue.

Retryable vs non-retryable

Every error has a retryable boolean. Use it to decide whether to surface a retry button or fail permanently.

Prop	Type	Default	Description
`ArlopassTransportError`	`retryable: true`	—	Transport failures are retryable by default.
`ArlopassTimeoutError`	`retryable: true`	—	Timeouts are retryable by default.
`ArlopassStateError`	`retryable: false`	—	State errors indicate logic bugs — not retryable.
`ArlopassInvalidStateTransitionError`	`retryable: false`	—	Invalid transitions are logic bugs — not retryable.
`ArlopassProtocolBoundaryError`	`retryable: false`	—	Protocol violations typically require a code fix.

if (error instanceof ArlopassSDKError && error.retryable) {
  await retry();
}