SDK error catalog
Every PasspointErrorCode value, what fires it, and how to recover.
Every SDK method that touches the OS or the network throws a
PasspointError with a typed code. Switch on e.code, not
e.message. Messages are unstable.
import { PasspointError, PasspointErrorCode } from '@helium/passpoint-sdk';
try {
await install(subscriberId);
} catch (e) {
if (e instanceof PasspointError) {
switch (e.code) {
case PasspointErrorCode.PERMISSION_DENIED:
// prompt for ACCESS_FINE_LOCATION
break;
case PasspointErrorCode.PROFILE_INSTALL_CANCELLED:
// user dismissed the iOS dialog
break;
case PasspointErrorCode.API_UNAUTHORIZED:
// bad key, surface to ops
break;
case PasspointErrorCode.NETWORK_ERROR:
// no connectivity, retry later
break;
}
}
}
Error codes
| Code | Platform | Description | Recovery |
|---|---|---|---|
NOT_CONFIGURED | Both | SDK not initialized. | Wrap your app in <PasspointProvider>. |
INVALID_CONFIG | Both | Bad config, for example an empty apiKey. | Fix the config; check env vars are loaded. |
PLATFORM_NOT_SUPPORTED | Both | Running on web or an unsupported platform. | Gate your UI on Platform.OS. |
SIMULATOR_NOT_SUPPORTED | iOS | Passpoint requires a physical device. | Test on hardware. |
PERMISSION_DENIED | Android | ACCESS_FINE_LOCATION not granted. | Request the permission, prompt the user, retry. |
MISSING_ENTITLEMENTS | iOS | Hotspot Configuration capability missing. | Add the entitlement in Xcode; rebuild. |
KEYPAIR_GENERATION_FAILED | Both | RSA keypair generation failed. | Surface to support; usually device-specific. |
CSR_GENERATION_FAILED | Both | Certificate signing request build failed. | Surface to support. |
NETWORK_ERROR | Both | Can't reach the Wi-Fi offload API. | Retry with backoff. |
API_ERROR | Both | API returned a non-2xx not covered below. | Inspect nativeError; surface to support. |
API_UNAUTHORIZED | Both | API key rejected (401 / 403). | Don't retry. Re-issue or rotate the key. |
API_RATE_LIMITED | Both | Too many requests (429). | Back off exponentially, honoring Retry-After. |
CERTIFICATE_PARSE_FAILED | Both | Couldn't parse the certificate in the API response. | Surface to support; likely a server-side bug. |
CERTIFICATE_SAVE_FAILED | Both | Keychain / KeyStore save failed. | Check entitlements (iOS) and KeyStore state (Android). |
CERTIFICATE_NOT_FOUND | Both | No certificate installed, during remove. | Treat as a no-op; UI should show "not installed". |
IDENTITY_LOAD_FAILED | iOS | Couldn't build a TLS identity from certificate and key. | Surface to support; usually a keychain group misconfiguration. |
PROFILE_INSTALL_FAILED | Both | The OS rejected the Passpoint profile. | Inspect nativeError; check entitlements and minSdk. |
PROFILE_INSTALL_CANCELLED | iOS | User dismissed the OS install dialog. | Prompt the user to retry. |
PROFILE_NOT_FOUND | Both | No profile to remove. | Treat as success. |
PROFILE_REMOVE_FAILED | Both | Failed to remove the profile. | Retry; if persistent, surface to support. |
REMOVE_FAILED | Both | Failed to remove certificate and profile together. | Retry; surface to support if persistent. |
WIFI_MANAGER_UNAVAILABLE | Android | WifiManager service unavailable. | Surface to support; device or OEM issue. |
NETWORK_SUGGESTION_DISALLOWED | Android | User blocked the app from adding Wi-Fi networks. | Send the user to system settings to allow suggestions. |
NETWORK_SUGGESTION_LIMIT | Android | Exceeded the maximum network suggestions per app. | Remove old suggestions, retry. |
UNKNOWN | Both | Unexpected error. | Inspect nativeError; surface to support. |
Inspecting nativeError
For codes that wrap an OS-level error, e.nativeError (a string) holds
the underlying message. Log it, but don't pattern-match on it. The text
isn't stable across OS versions.