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	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`
`details`	` Record<string, string	number
`cause`	` Error	undefined`

SDK machine codes

Codes prefixed with ARLOPASS_SDK_ originate in the client SDK.

Prop	Type	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	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	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	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();
}