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

# Known Errors

> Reference for Hexclave known errors exposed by public TypeScript SDK types

Hexclave uses known errors for expected, actionable failures. Some public SDK methods return `Result<..., KnownErrors["..."]>` in their TypeScript signatures. This page lists only the known errors currently exposed through those public TypeScript types.

<Info>
  Hexclave has additional internal known errors for API implementation details.
  They are intentionally not part of this public SDK reference.
</Info>

At runtime, known errors include a stable `errorCode` value. In the REST API, the same value appears as the JSON `code` field and the `X-Stack-Known-Error` response header.

```json theme={null}
{
  "code": "EMAIL_PASSWORD_MISMATCH",
  "error": "Wrong e-mail or password."
}
```

## Handling known errors

When using SDK methods that return `Result`, check `result.status` and inspect `result.error`.

```ts theme={null}
const result = await hexclaveClientApp.signInWithCredential({
  email,
  password,
});

if (result.status === "error") {
  console.log(result.error.errorCode);
}
```

Check specific errors by comparing `error.errorCode`:

```ts theme={null}
if (result.error.errorCode === "EMAIL_PASSWORD_MISMATCH") {
  // Show "wrong email or password" UI.
}
```

For REST API calls, read the `code` field from the JSON response body.

<Info>
  Error messages are human-readable and may include request-specific details.
  Use `code` for programmatic handling.
</Info>

## Exposed known errors

| Public TypeScript type                                      | Runtime `errorCode`                                  | Returned by                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KnownErrors["EmailPasswordMismatch"]`                      | `EMAIL_PASSWORD_MISMATCH`                            | `hexclaveClientApp.signInWithCredential()`                                                                                                                                                                                                                                                                                                        |
| `KnownErrors["InvalidTotpCode"]`                            | `INVALID_TOTP_CODE`                                  | `hexclaveClientApp.signInWithCredential()`, `hexclaveClientApp.signInWithMagicLink()`, `hexclaveClientApp.signInWithMfa()`, `hexclaveClientApp.signInWithPasskey()`                                                                                                                                                                               |
| `KnownErrors["UserWithEmailAlreadyExists"]`                 | `USER_EMAIL_ALREADY_EXISTS`                          | `hexclaveClientApp.signUpWithCredential()`                                                                                                                                                                                                                                                                                                        |
| `KnownErrors["PasswordRequirementsNotMet"]`                 | `PASSWORD_REQUIREMENTS_NOT_MET`                      | `hexclaveClientApp.signUpWithCredential()`, `user.updatePassword()`, `user.setPassword()`                                                                                                                                                                                                                                                         |
| `KnownErrors["BotChallengeFailed"]`                         | `BOT_CHALLENGE_FAILED`                               | `hexclaveClientApp.signUpWithCredential()`, `hexclaveClientApp.sendMagicLinkEmail()`                                                                                                                                                                                                                                                              |
| `KnownErrors["PasskeyAuthenticationFailed"]`                | `PASSKEY_AUTHENTICATION_FAILED`                      | `hexclaveClientApp.signInWithPasskey()`                                                                                                                                                                                                                                                                                                           |
| `KnownErrors["PasskeyRegistrationFailed"]`                  | `PASSKEY_REGISTRATION_FAILED`                        | `user.registerPasskey()`                                                                                                                                                                                                                                                                                                                          |
| `KnownErrors["PasskeyWebAuthnError"]`                       | `PASSKEY_WEBAUTHN_ERROR`                             | `hexclaveClientApp.signInWithPasskey()`, `user.registerPasskey()`                                                                                                                                                                                                                                                                                 |
| `KnownErrors["CliAuthError"]`                               | `CLI_AUTH_ERROR`                                     | `hexclaveClientApp.promptCliLogin()`                                                                                                                                                                                                                                                                                                              |
| `KnownErrors["CliAuthExpiredError"]`                        | `CLI_AUTH_EXPIRED_ERROR`                             | `hexclaveClientApp.promptCliLogin()`                                                                                                                                                                                                                                                                                                              |
| `KnownErrors["CliAuthUsedError"]`                           | `CLI_AUTH_USED_ERROR`                                | `hexclaveClientApp.promptCliLogin()`                                                                                                                                                                                                                                                                                                              |
| `KnownErrors["UserNotFound"]`                               | `USER_NOT_FOUND`                                     | `hexclaveClientApp.sendForgotPasswordEmail()`                                                                                                                                                                                                                                                                                                     |
| `KnownErrors["RedirectUrlNotWhitelisted"]`                  | `REDIRECT_URL_NOT_WHITELISTED`                       | `hexclaveClientApp.sendMagicLinkEmail()`                                                                                                                                                                                                                                                                                                          |
| `KnownErrors["VerificationCodeError"]`                      | `VERIFICATION_ERROR`                                 | `hexclaveClientApp.resetPassword()`, `hexclaveClientApp.verifyPasswordResetCode()`, `hexclaveClientApp.verifyTeamInvitationCode()`, `hexclaveClientApp.acceptTeamInvitation()`, `hexclaveClientApp.getTeamInvitationDetails()`, `hexclaveClientApp.verifyEmail()`, `hexclaveClientApp.signInWithMagicLink()`, `hexclaveClientApp.signInWithMfa()` |
| `KnownErrors["OAuthAccessTokenNotAvailable"]`               | `OAUTH_ACCESS_TOKEN_NOT_AVAILABLE`                   | `connectedAccount.getAccessToken()`, `connectedAccount.useAccessToken()`                                                                                                                                                                                                                                                                          |
| `KnownErrors["OAuthProviderAccountIdAlreadyUsedForSignIn"]` | `OAUTH_PROVIDER_ACCOUNT_ID_ALREADY_USED_FOR_SIGN_IN` | `oauthProvider.update()`, `serverOAuthProvider.update()`, `hexclaveServerApp.createOAuthProvider()`                                                                                                                                                                                                                                               |
| `KnownErrors["EmailAlreadyVerified"]`                       | `EMAIL_ALREADY_VERIFIED`                             | `user.sendVerificationEmail()`                                                                                                                                                                                                                                                                                                                    |
| `KnownErrors["PasswordConfirmationMismatch"]`               | `PASSWORD_CONFIRMATION_MISMATCH`                     | `user.updatePassword()`                                                                                                                                                                                                                                                                                                                           |

## Parent error types

Some exposed types are parent classes for more specific errors. For example:

* `KnownErrors["PasswordRequirementsNotMet"]` may currently have `PASSWORD_TOO_SHORT` or `PASSWORD_TOO_LONG` as the runtime `errorCode`.
* `KnownErrors["VerificationCodeError"]` may currently have `VERIFICATION_CODE_NOT_FOUND`, `VERIFICATION_CODE_EXPIRED`, `VERIFICATION_CODE_ALREADY_USED`, or `VERIFICATION_CODE_MAX_ATTEMPTS_REACHED` as the runtime `errorCode`.

When you only need broad handling, check the parent type returned in TypeScript. When you need precise UI copy, compare `error.errorCode` against the specific runtime code.