> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Passkey Error Codes

> Reference for structured passkey error codes in the React Native and Expo SDKs

export const Link = ({href, label, newTab = false}) => {
  const [isHovered, setIsHovered] = useState(false);
  return <a href={href} target={newTab ? '_blank' : '_self'} rel={newTab ? 'noopener noreferrer' : undefined} className="not-prose inline-block relative text-black font-semibold cursor-pointer border-b-0 no-underline" onMouseEnter={() => setIsHovered(true)} onMouseLeave={() => setIsHovered(false)}>
      {label}
      <span className={`absolute left-0 bottom-0 w-full rounded-sm bg-gradient-to-r from-orange-600 to-purple-600 transition-all duration-300 ${isHovered ? 'h-0.5' : 'h-px'}`} />
    </a>;
};

The React Native SDK wraps native passkey errors from iOS and Android into `ParaPasskeyError`, a structured error class
with a typed error code, platform detection, an actionable suggestion, and a link back to this page. Every passkey
operation (`registerPasskey`, `loginWithPasskey`) throws a `ParaPasskeyError` on failure.

```ts theme={null}
import { ParaPasskeyError } from "@getpara/react-native-sdk";

try {
  await para.registerPasskey(authState);
} catch (error) {
  if (error instanceof ParaPasskeyError) {
    console.log(error.code);       // "RP_ID_MISMATCH"
    console.log(error.platform);   // "android"
    console.log(error.suggestion); // actionable fix
  }
}
```

Each error includes these properties:

| Property     | Type                              | Description                                      |
| ------------ | --------------------------------- | ------------------------------------------------ |
| `code`       | `ParaPasskeyErrorCode`            | Machine-readable error code from the table below |
| `platform`   | `'ios' \| 'android' \| 'unknown'` | Platform that produced the error                 |
| `message`    | `string`                          | Original error message from the native layer     |
| `suggestion` | `string`                          | Actionable guidance for resolving the error      |
| `docsUrl`    | `string`                          | Direct link to the relevant section on this page |
| `cause`      | `unknown`                         | Original error object for deep debugging         |

## USER\_CANCELLED

The user dismissed the passkey prompt (tapped cancel, swiped away, or declined biometric authentication).

**Platforms:** iOS, Android

**What to do:** This is expected behavior. Handle it gracefully by catching the error and allowing the user to retry.
Do not treat this as a fatal error or show an error screen.

## TIMED\_OUT

The passkey operation exceeded the system timeout before the user completed the biometric prompt.

**Platforms:** iOS, Android

**What to do:** Prompt the user to try again. If this happens frequently, check whether the timeout configuration in
your passkey request is too short for your users' environment.

## BAD\_CONFIGURATION

The app's entitlements, associated domains, or passkey request parameters are misconfigured.

**Platforms:** iOS, Android

**What to do:**

* **iOS:** Verify that your Xcode project (or `app.json` for Expo) includes the associated domains entitlement with
  `webcredentials:app.beta.usecapsule.com` and `webcredentials:app.usecapsule.com`. Confirm your Team ID and Bundle ID
  are registered in the <Link label="Developer Portal" href="https://developer.getpara.com" />.
* **Android:** Verify your SHA-256 signing certificate fingerprint is registered in the <Link label="Developer Portal" href="https://developer.getpara.com" /> under your API key's Native Passkey
  Configuration.

<Note>
  This code also covers `InvalidChallenge` and `InvalidUser` errors from the native layer, which indicate malformed
  request parameters. These are typically SDK internal issues — if you encounter them, please <Link label="contact support" href="https://getpara.com/support" />.
</Note>

## NOT\_CONFIGURED

The credential provider is not set up on the device.

**Platforms:** Android

**What to do:** This is Android-specific. Ensure Google Play Services is available and that a Google account is signed
in on the device. Devices without Google Play Services (some Huawei devices, custom ROMs) cannot use passkeys through
the Credential Manager API.

## RP\_ID\_MISMATCH

The app's signing certificate does not match what is registered for the relying party domain.

**Platforms:** Android

**What to do:** This is the most common Android passkey error. Debug and release builds use different signing keys, and
the SHA-256 fingerprint registered in the Developer Portal must match the build you are testing.

Get your debug fingerprint:

```bash theme={null}
keytool -list -v -keystore ~/.android/debug.keystore \
  -alias androiddebugkey -storepass android -keypass android
```

Get your release fingerprint:

```bash theme={null}
keytool -list -v -keystore <your_keystore_path>
```

Register both fingerprints in the <Link label="Developer Portal" href="https://developer.getpara.com" /> to avoid this
error across build types.

<Warning>
  After registering a new fingerprint, Google can take up to 24 hours to verify it. Check the verification status in
  the Developer Portal under your API key's Native Passkey Configuration.
</Warning>

## NOT\_SUPPORTED

Passkeys are not supported on this device.

**Platforms:** iOS, Android

**What to do:** Passkeys require iOS 16+ or Android API 28+. If the device does not meet these requirements, fall back
to an alternative authentication method (email OTP, password, or social login). Use this error code to detect
unsupported devices and present the appropriate fallback UI.

## NO\_CREDENTIALS

No passkeys are stored on this device for the requested user.

**Platforms:** Android (login only)

**What to do:** This means the user has not registered a passkey on this device, or is on a different device than where
the passkey was created. Ensure your auth flow calls `registerPasskey()` for new users before attempting
`loginWithPasskey()`. If the user previously registered on another device, they will need to register again on this one
or use cross-device passkey authentication if supported.

## REQUEST\_FAILED

The passkey request failed at the system level.

**Platforms:** iOS, Android

**What to do:**

* **iOS:** Check that your associated domains entitlement is configured correctly and that your Team ID and Bundle ID
  are registered in the <Link label="Developer Portal" href="https://developer.getpara.com" />. Also verify the device
  can reach Apple's CDN to validate the Apple App Site Association file.
* **Android:** Verify your SHA-256 fingerprint is registered correctly. See the [RP\_ID\_MISMATCH](#rp_id_mismatch)
  section for fingerprint instructions.

## INTERRUPTED

The passkey operation was interrupted by the system before it could complete.

**Platforms:** iOS, Android

**What to do:** This can happen when the app is backgrounded during a passkey operation, or when another authentication
prompt takes priority. The operation can be safely retried.

## UNKNOWN

An unrecognized error occurred during the passkey operation.

**Platforms:** iOS, Android

**What to do:** Check the `cause` property on the error object for the original native error details. If the error
persists, <Link label="contact support" href="https://getpara.com/support" /> with the full error output from the
development console. In development builds, the SDK automatically logs a diagnostic block with the error code, platform,
relying party ID, and suggestion.

### Integration Support

If you're experiencing issues that aren't resolved by our troubleshooting resources, please [contact our team](https://join.slack.com/t/para-community/shared_invite/zt-304keeulc-Oqs4eusCUAJEpE9DBwAqrg) for
assistance. To help us resolve your issue quickly, please include the following information in your request:

<ol className="space-y-4 list-none pl-0">
  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      1
    </span>

    <p className="flex-1 my-0">A detailed description of the problem you're encountering.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      2
    </span>

    <p className="flex-1 my-0">Any relevant error messages or logs.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      3
    </span>

    <p className="flex-1 my-0">Steps to reproduce the issue.</p>
  </li>

  <li className="flex items-start">
    <span className="w-7 h-7 shrink-0 rounded-lg bg-gray-100 mr-2 mt-0.5 dark:text-white dark:bg-[#26292E] text-sm text-gray-800 font-semibold flex items-center justify-center">
      4
    </span>

    <p className="flex-1 my-0">Details about your system or environment (e.g., device, operating system, software version).</p>
  </li>
</ol>

Providing this information will enable our team to address your concerns more efficiently.