Frontend API errors
{
"shortMessage": "actor token has already been used",
"longMessage": "This actor token has already been used. Each token can only be used once.",
"code": "actor_token_already_used_code"
}{
"shortMessage": "not in sign in",
"longMessage": "Actor tokens can only be used during sign in.",
"code": "actor_token_not_in_sign_in_code"
}{
"shortMessage": "actor token cannot be used",
"longMessage": "This actor token cannot be used anymore. Please request a new one.",
"code": "actor_token_cannot_be_used_code"
}{
"shortMessage": "actor token has been revoked",
"longMessage": "This actor token has been revoked and cannot be used anymore.",
"code": "actor_token_revoked_code"
}{
"shortMessage": "user not found",
"longMessage": "The user of the actor token no longer exists. Please request a new one.",
"code": "actor_token_subject_not_found"
}{
"shortMessage": "agent task has already been used",
"longMessage": "This agent task has already been used. Each task can only be used once.",
"code": "agent_task_already_used"
}{
"shortMessage": "not in sign in",
"longMessage": "Agent tasks can only be used during sign in.",
"code": "agent_task_not_in_sign_in"
}{
"shortMessage": "agent task cannot be used",
"longMessage": "This agent task cannot be used anymore. Please request a new one.",
"code": "agent_task_cannot_be_used"
}{
"shortMessage": "agent task has been revoked",
"longMessage": "This agent task has been revoked and cannot be used anymore.",
"code": "agent_task_revoked"
}{
"shortMessage": "user not found",
"longMessage": "The user of the agent task no longer exists. Please request a new one.",
"code": "agent_task_subject_not_found"
}{
"shortMessage": "API Keys not enabled",
"longMessage": "API Keys not enabled",
"code": "api_keys_not_enabled"
}Applications
ManagementTokenSubjectNotFound is returned when redeeming a management
token whose referenced user no longer exists in the instance.
{
"shortMessage": "user not found",
"longMessage": "The user referenced by this management token no longer exists. Mint a new token.",
"code": "management_token_subject_not_found"
}Auth
DevBrowserUnauthenticated signifies an error when the dev browser is not authenticated
{
"shortMessage": "Browser unauthenticated",
"longMessage": "Unable to authenticate this browser for your development instance. Check your Clerk cookies and try again. If the issue persists reach out to support@clerk.com.",
"code": "dev_browser_unauthenticated"
}
IdentificationExists signifies an error when the identifier already exists
{
"shortMessage": "already exists",
"longMessage": "This <identifier> already exists.",
"code": ""
}{
"shortMessage": "Email subaddress not allowed.",
"longMessage": "Email address must not contain the characters '+', '=', or '#'.",
"code": "not_allowed_access",
"meta": {
"name": "email_address"
}
}{
"shortMessage": "Country code not allowed.",
"longMessage": "Phone number sign ups are not allowed for this country code. Please use a different method.",
"code": "not_allowed_access",
"meta": {
"name": "phone_number"
}
}{
"shortMessage": "Access not allowed.",
"longMessage": "<who> <pluralization> not allowed to access this application.",
"code": "not_allowed_access",
"meta": "{\"Identifiers\": identifiers}"
}
InvalidAuthentication signifies an error when the request is not authenticated
{
"shortMessage": "Invalid authentication",
"longMessage": "Unable to authenticate the request, you need to supply an active session",
"code": "authentication_invalid"
}
InvalidAuthorization signifies an error when the request is not authorized to perform the given operation
{
"shortMessage": "Unauthorized request",
"longMessage": "You are not authorized to perform this request",
"code": "authorization_invalid"
}
InvalidAuthorizationHeaderFormat signifies an error when the Authorization header has no proper format.
{
"shortMessage": "Invalid Authorization header format",
"longMessage": "Invalid Authorization header format. Must be 'Bearer <YOUR_API_KEY>'",
"code": "authorization_header_format_invalid"
}
InvalidCSRFToken signifies an error when the request does not contain a CSRF token or the given token is invalid
{
"shortMessage": "Invalid or missing CSRF token",
"longMessage": "To protect against CSRF attacks, the given request must include a valid CSRF token.",
"code": "csrf_token_invalid"
}{
"shortMessage": "invalid handshake",
"longMessage": "The handshake request is invalid: <reason>",
"code": "invalid_handshake"
}
InvalidHost signifies an error when the incoming request has an invalid host
{
"shortMessage": "Invalid host",
"longMessage": "We were unable to attribute this request to an instance running on Clerk. Make sure that your Clerk Publishable Key is correct.",
"code": "host_invalid"
}
InvalidOriginHeader signifies an error when the origin header of the incoming request is invalid
{
"shortMessage": "Invalid HTTP Origin header",
"longMessage": "The Request HTTP Origin header must be equal to or a subdomain of the requesting URL.",
"code": "origin_invalid"
}
InvalidRequestForEnvironment signifies an error when the incoming request is invalid for given environment(s)
{
"shortMessage": "Invalid request for environment",
"longMessage": "Request only valid for <envTypes> instances.",
"code": "request_invalid_for_environment"
}
InvalidUserSettings signifies an error where the auth settings of the instance
are not well configured, which results in sign in and sign up endpoints to be
restricted.
{
"shortMessage": "invalid auth configuration",
"longMessage": "The authentication settings are invalid.",
"code": "user_settings_invalid"
}{
"shortMessage": "Multiple 'Authorization' header values",
"longMessage": "Setting multiple values in the 'Authorization' header is forbidden",
"code": "multiple_authorization_header_values_forbidden"
}{
"shortMessage": "Multiple 'Origin' header values",
"longMessage": "Setting multiple values in the 'Origin' header is forbidden",
"code": "multiple_origin_header_values_forbidden"
}
NativeAPIDisabled signifies an error when the incoming request is from a native client (\_is\_native={1|true})
and the instance is not configured to allow native API requests.
{
"shortMessage": "Native API disabled",
"longMessage": "The Native API is disabled for this instance. Visit the Clerk Dashboard to enable it.",
"code": "native_api_disabled"
}{
"shortMessage": "Setting both the 'Origin' and 'Authorization' headers is forbidden",
"longMessage": "For security purposes, only one of the 'Origin' and 'Authorization' headers should be provided, but not both. In browser contexts, the 'Origin' header is set automatically by the browser. In native application contexts (e.g. mobile apps), set the 'Authorization' header.",
"code": "origin_authorization_headers_conflict"
}
supportEmail (_) is unused here at the moment the customer who requested this change specifically wanted to avoid adding a support email since changing this is not in control of support. reference: https://clerkinc.slack.com/archives/C07U96ZAZ9T/p1759344749115659?thread_ts=1758659910.343909&cid=C07U96ZAZ9T
{
"shortMessage": "Rate limited country code",
"longMessage": "SMS to the country <countryName> is temporarily disabled. Please try again later.",
"code": "unsupported_country_code",
"meta": "{\"Alpha2\": alpha2, \"CountryCode\": countryCode}"
}
SignedOut signifies an error when a user is signed out
{
"shortMessage": "Signed out",
"longMessage": "You are signed out",
"code": "signed_out"
}{
"shortMessage": "This email address is already in use.",
"longMessage": "This email address is already in use. Creating multiple accounts with the same email address is not allowed.",
"code": "not_allowed_access"
}
SubdomainNotAllowed signifies an error when the subdomain is not in the allowlist
{
"shortMessage": "Subdomain not allowed",
"longMessage": "The request origin subdomain is not in the allowed subdomains list. Please add it to your subdomain allowlist in the Dashboard.",
"code": "subdomain_not_allowed"
}{
"shortMessage": "Unsupported country code",
"longMessage": "Phone numbers from this country (<countryName>) are currently not supported. For more information, please contact <support>.",
"code": "unsupported_country_code",
"meta": "{\"Alpha2\": alpha2, \"CountryCode\": countryCode}"
}
URLBasedSessionSyncingDisabled signifies an error when the incoming request attempts
to use an endpoint with URL-based session syncing, when the instance operates with
third-party cookies instead.
{
"shortMessage": "URL-based session syncing is disabled for this instance",
"longMessage": "This is a development instance operating with legacy, third-party cookies. This feature is deprecated, please contact support if you need assistance.",
"code": "url_based_session_syncing_disabled"
}{
"shortMessage": "ADMIN_USER_PASSWORD_AUTH flow not enabled for this AWS Cognito client.",
"longMessage": "ADMIN_USER_PASSWORD_AUTH flow not enabled for this AWS Cognito client. Ensure that your Cognito user pool has a public client with the ALLOW_ADMIN_USER_PASSWORD_AUTH auth flow enabled.",
"code": "aws_cognito_admin_user_password_auth_not_enabled"
}{
"shortMessage": "AWS Cognito user validation failed.",
"longMessage": "The sign-in attempt was rejected by the AWS Cognito user validation Lambda trigger.",
"code": "aws_cognito_user_lambda_validation_failed"
}{
"shortMessage": "USER_PASSWORD_AUTH flow not enabled for this AWS Cognito client.",
"longMessage": "USER_PASSWORD_AUTH flow not enabled for this AWS Cognito client. Ensure that your Cognito user pool has a public client with the ALLOW_USER_PASSWORD_AUTH auth flow enabled.",
"code": "aws_cognito_user_password_auth_not_enabled"
}{
"shortMessage": "Backup codes not available",
"longMessage": "In order to use backup codes, you have to enable any other Multi-factor method",
"code": "backup_codes_not_available"
}{
"shortMessage": "Client not found",
"longMessage": "No client was found with id <clientID>",
"code": "resource_not_found"
}
ClientNotFoundInRequest signifies an error when no client is found in an incoming request
{
"shortMessage": "No client found",
"longMessage": "This request is expecting a client and did not find one",
"code": "client_not_found"
}{
"shortMessage": "Annual plan period not supported",
"longMessage": "Annual plan period not supported",
"code": "annual_plan_period_not_supported"
}{
"shortMessage": "access denied",
"longMessage": "The billing feature is not enabled for this instance. You can enable it at https://dashboard.clerk.com.",
"code": "billing_not_enabled"
}{
"shortMessage": "access denied",
"longMessage": "The billing feature for organizations is not enabled for this instance. You can enable it at https://dashboard.clerk.com.",
"code": "billing_not_enabled"
}{
"shortMessage": "access denied",
"longMessage": "The billing feature for users is not enabled for this instance. You can enable it at https://dashboard.clerk.com.",
"code": "billing_not_enabled"
}{
"shortMessage": "Plan is not Publicly available",
"longMessage": "Plan is not Publicly available, and should not be used in checkout",
"code": "billing_plan_is_hidden"
}{
"shortMessage": "Checkout already complete",
"longMessage": "Checkout already complete",
"code": "checkout_already_complete"
}{
"shortMessage": "Another checkout is already in progress",
"longMessage": "Another checkout is already in progress",
"code": "checkout_already_in_progress"
}{
"shortMessage": "Checkout not found",
"longMessage": "Checkout not found",
"code": "checkout_not_found"
}{
"shortMessage": "Insufficient seats",
"longMessage": "You have reached the seat limit for your current plan.",
"code": "insufficient_seats",
"meta": {
"seatsquantity": "totalneeded"
}
}{
"shortMessage": "Statement not found",
"longMessage": "No statement found with id <statementID>.",
"code": "commerce_statement_not_found"
}{
"shortMessage": "Subscription item already canceled",
"longMessage": "You can't cancel a subscription item that is already canceled",
"code": "commerce_subscription_item_already_canceled"
}{
"shortMessage": "Subscription item cannot be canceled",
"longMessage": "Subscription item cannot be canceled because <reason>",
"code": "commerce_subscription_item_cannot_be_canceled"
}{
"shortMessage": "Subscription item cannot be ended",
"longMessage": "Subscription item cannot be ended because <reason>",
"code": "commerce_subscription_item_cannot_be_ended"
}{
"shortMessage": "External payments not setup",
"longMessage": "External payments not setup",
"code": "external_payments_not_setup"
}
FreeTrialAlreadyActive is returned when a payer tries to check out for the
same plan/period they are already free-trialing. Seat additions on the
active trial are allowed; this error covers the stale "Start free trial"
re-checkout path that would otherwise convert the trial into a $0 paid item.
{
"shortMessage": "Free trial already active",
"longMessage": "You already have an active free trial for this plan.",
"code": "free_trial_already_active"
}{
"shortMessage": "Invalid gateway type",
"longMessage": "Gateway type is invalid",
"code": "invalid_gateway_type"
}{
"shortMessage": "Invalid plan change",
"longMessage": "Please choose a different plan or billing interval, or contact support.",
"code": "invalid_plan_change",
"meta": "{\"Plan\": {\"ID\": \"planID\", \"Name\": \"planName\", \"CurrencySymbol\": \"currencySymbol\", \"AmountFormatted\": \"amountFormatted\", \"AnnualAmountFormatted\": \"annualMonthlyAmountFormatted\"}, \"Period\": period, \"IsPlanUpgradePossible\": isPlanUpgradePossible}"
}{
"shortMessage": "Invalid plan type",
"longMessage": "Plan type (<planType>) is invalid",
"code": "invalid_plan_type"
}{
"shortMessage": "Invalid use of test card",
"longMessage": "Test card cannot be used in production environment.",
"code": "invalid_use_of_test_card"
}{
"shortMessage": "Max payment methods quota exceeded",
"longMessage": "You have reached your limit of %d payment methods. Please delete a payment source to add a new one.",
"code": "max_payment_methods_quota_exceeded"
}{
"shortMessage": "Missing payer email",
"longMessage": "Payer email is required to perform this operation",
"code": "missing_payer_email"
}{
"shortMessage": "Missing plan ID",
"longMessage": "Plan ID is required to perform this operation",
"code": "missing_plan_id"
}{
"shortMessage": "Monthly plan period not supported",
"longMessage": "Monthly plan period not supported",
"code": "monthly_plan_period_not_supported"
}{
"shortMessage": "Organization member limit exceeded",
"longMessage": "Plan change is not allowed because the organization's <occupiedSeatsStr> occupied seats exceed the limit of <maxAllowedStr> organization memberships.",
"code": "org_member_limit_exceeded_for_plan_change"
}{
"shortMessage": "Payee not active",
"longMessage": "Payee is not active",
"code": "payee_not_active"
}{
"shortMessage": "Payee not found",
"longMessage": "Payee not found",
"code": "payee_not_found"
}{
"shortMessage": "Payer not found",
"longMessage": "Payer not found",
"code": "payer_not_found"
}{
"shortMessage": "Requires confirmation",
"longMessage": "The payment attempt failed because it requires additional confirmation, which is not currently supported. Please use a different payment method.",
"code": "payment_attempt_failed_requires_confirmation"
}{
"shortMessage": "Your card was declined",
"longMessage": "The card was declined.",
"code": "payment_attempt_failed_card_declined"
}{
"shortMessage": "Card expired",
"longMessage": "The card has expired.",
"code": "payment_attempt_failed_card_expired"
}{
"shortMessage": "Insufficient funds",
"longMessage": "The card has insufficient funds.",
"code": "payment_attempt_failed_card_insufficient_funds"
}{
"shortMessage": "Processing error",
"longMessage": "There was a processing error with the payment method.",
"code": "payment_attempt_failed_processing_error"
}{
"shortMessage": "Payment method is expired",
"longMessage": "Payment method is expired",
"code": "payment_source_expired"
}{
"shortMessage": "Payment source in use",
"longMessage": "Payment source is in use, as you have active subscriptions. Please cancel those subscriptions before deleting the payment source.",
"code": "payment_source_in_use"
}{
"shortMessage": "Payment source not found",
"longMessage": "Payment source not found",
"code": "payment_source_not_found"
}{
"shortMessage": "Plan already active",
"longMessage": "Plan already active",
"code": "plan_already_active"
}{
"shortMessage": "Plan cannot have seats",
"longMessage": "The selected plan is not seat-based, but the checkout request included a seat_quantity.",
"code": "plan_cannot_have_seats"
}{
"shortMessage": "Plan not found",
"longMessage": "Plan not found",
"code": "plan_not_found"
}{
"shortMessage": "Plan seat limit exceeded",
"longMessage": "Your organization has <currentMembersStr> members, but the requested plan would only support <seatLimitStr> members. Please remove members before switching to this plan.",
"code": "plan_seat_limit_exceeded",
"meta": "{\"PlanSeatLimit\": planSeatLimit, \"CurrentMembers\": currentMembers}"
}{
"shortMessage": "Invalid price_id for checkout",
"longMessage": "You cannot checkout with that price.",
"code": "price_id_invalid_for_checkout"
}{
"shortMessage": "Requested seats insufficient",
"longMessage": "Your organization has <currentMembersStr> members but this checkout only grants <grantedSeatsStr> seats. Please request at least <currentMembersStr> seats or remove members.",
"code": "requested_seats_insufficient",
"meta": "{\"PlanSeatLimit\": grantedSeats, \"CurrentMembers\": currentMembers}"
}{
"shortMessage": "Seat-based billing exceeds plan's organization member limit",
"longMessage": "The seat-based plan you are trying to create exceeds your Clerk plan's organization member limit. Adjust your seat limits to match your plan's limit or upgrade your subscription.",
"code": "seat_based_billing_exceeds_org_member_limit"
}{
"shortMessage": "Seat reduction not supported in checkout",
"longMessage": "Seats cannot be reduced through checkout.",
"code": "seat_reduction_in_checkout_not_supported"
}{
"shortMessage": "Subscription already ended",
"longMessage": "Subscription is already ended",
"code": "subscription_already_ended"
}{
"shortMessage": "Subscription item not found",
"longMessage": "Subscription item not found",
"code": "subscription_item_not_found"
}{
"shortMessage": "Discount inactive",
"longMessage": "This discount is not currently active",
"code": "discount_inactive"
}{
"shortMessage": "Discount not applicable",
"longMessage": "This discount cannot be applied to this checkout",
"code": "discount_not_applicable"
}{
"shortMessage": "Discount not found",
"longMessage": "The discount was not found",
"code": "discount_not_found"
}Domains
FeatureRequiresCustomDomain signifies an error when a feature is blocked
because the instance only has a provider domain (e.g. vercel.app).
{
"shortMessage": "custom domain required",
"longMessage": "<feature> requires a custom domain. Add a custom domain to unlock this feature.",
"code": "feature_requires_custom_domain"
}{
"shortMessage": "",
"longMessage": "Clerk Frontend API cannot be accessed through the proxy URL. Make sure your proxy is configured correctly.",
"code": "invalid_proxy_configuration",
"meta": {
"name": "proxy_url"
}
}{
"shortMessage": "operation not allowed",
"longMessage": "This operation is not allowed on a satellite domain. Try again using the primary domain of your instance.",
"code": "operation_not_allowed_on_satellite_domain"
}
SyncNonceAlreadyConsumed signifies an error when the nonce that was given
during the sync flow is already consumed.
{
"shortMessage": "sync nonce already consumed",
"longMessage": "The given sync nonce has already been consumed and cannot be re-used.",
"code": "sync_nonce_already_consumed"
}
DevMonthlyEmailLimitExceeded signifies an error when an email sending attempt is made while the development limit has already been reached
{
"shortMessage": "Development monthly email limit exceeded",
"longMessage": "The monthly limit for email messages in development (%d) has been reached. Please use test emails (https://go.clerk.com/test-emails) instead",
"code": "dev_monthly_email_limit_exceeded",
"meta": "{\"DevMonthlyEmailLimit\": limit}"
}{
"shortMessage": "Enterprise Connection ID is required with multiple connections",
"longMessage": "The Enterprise Connection ID is required with multiple connections.",
"code": "enterprise_connection_id_is_required_with_multiple_connections"
}{
"shortMessage": "Invalid enterprise connection type",
"longMessage": "The enterprise connection type is not supported.",
"code": "enterprise_connection_invalid_type"
}{
"shortMessage": "Connection name is required",
"longMessage": "A connection name could not be derived by default. Please provide a name for the enterprise connection.",
"code": "enterprise_connection_name_not_derivable",
"meta": {
"name": "param"
}
}{
"shortMessage": "Already connected",
"longMessage": "An enterprise account is already connected for this connection email: <email>",
"code": "enterprise_sso_account_already_connected"
}{
"shortMessage": "Identifications creation disabled by your enterprise account",
"longMessage": "You cannot create identifications because your enterprise account does not allow it.",
"code": "enterprise_sso_additional_identifications_disabled"
}{
"shortMessage": "Enterprise Connection email address domain mismatch",
"longMessage": "The email address returned by the provider <received> does not match the domain of the enterprise connection <expected> that initiated the authentication.",
"code": "enterprise_sso_email_address_domain_mismatch",
"meta": {
"expecteddomain": "expected",
"receiveddomain": "received"
}
}{
"shortMessage": "Hosted domain mismatch",
"longMessage": "The Enterprise Connection domain does not match the user's hosted domain from the OAuth provider.",
"code": "enterprise_sso_hosted_domain_mismatch"
}{
"shortMessage": "No Enterprise Connection for this sign-in",
"longMessage": "The current sign-in does not have a corresponding Enterprise Connection. Please check the domain of the provided email address.",
"code": "enterprise_sso_sign_in_connection_missing"
}{
"shortMessage": "No Enterprise Connection for this sign-up",
"longMessage": "The current sign-up does not have a corresponding Enterprise Connection. Please check the domain of the provided email address.",
"code": "enterprise_sso_sign_up_connection_missing"
}{
"shortMessage": "Enterprise Connection email address missing",
"longMessage": "The Enterprise Connection did not return the required '<attrName>' attribute. Contact the IdP administrator to ensure it is included in the identity response.",
"code": "enterprise_sso_user_attribute_missing",
"meta": {
"missingattribute": "attrname"
}
}{
"shortMessage": "self-serve SSO not enabled",
"longMessage": "The self-serve SSO feature is not enabled for this instance.",
"code": "self_serve_sso_disabled"
}
SelfServeSSONoActiveOrganization signals that the session has no
last_active_organization_id. Self-serve SSO is per-org; an active org context
is required before any enterprise connection can be created.
{
"shortMessage": "no active organization",
"longMessage": "Self-serve SSO requires an active organization. Switch to an organization before creating an enterprise connection.",
"code": "self_serve_sso_no_active_organization"
}
SelfServeSSOOrganizationDisabled signals that the active organization does
not have the self-serve SSO toggle enabled.
{
"shortMessage": "self-serve SSO not enabled for organization",
"longMessage": "Self-serve SSO is not enabled for the active organization.",
"code": "self_serve_sso_organization_disabled"
}{
"shortMessage": "not enabled",
"longMessage": "This feature is not enabled on this instance",
"code": "feature_not_enabled"
}{
"shortMessage": "Device authorization grant is not enabled",
"longMessage": "The OAuth 2.0 device authorization grant is not enabled for this instance. Please contact support to enable this feature",
"code": "feature_requires_device_authorization_grant"
}{
"shortMessage": "Device verification page is not reachable",
"longMessage": "This feature requires a reachable device verification page. Configure a device verification URL or enable the Account Portal for this instance to continue.",
"code": "feature_requires_device_verification_url"
}{
"shortMessage": "dynamic client registration is not enabled",
"longMessage": "Dynamic client registration is not enabled on this instance. Please enable it in the instance settings to use this feature",
"code": "feature_requires_dynamic_oauth_client_registration"
}{
"shortMessage": "Email address attribute must be enabled",
"longMessage": "This feature requires the email address attribute to be enabled. Please enable it in your instance settings to continue.",
"code": "feature_requires_email_address_enabled"
}{
"shortMessage": "End session feature is not enabled",
"longMessage": "The end session feature is not enabled for this instance. Please contact support to enable this feature",
"code": "feature_requires_end_session_enabled"
}{
"shortMessage": "OAuth Client does not have the consent screen enabled",
"longMessage": "OAuth Client does not have the consent screen enabled, please enable it in the OAuth Client settings to use this feature",
"code": "feature_requires_oauth2_consent_screen_enabled"
}{
"shortMessage": "not an OIDC provider",
"longMessage": "You are using the legacy OAuth 2.0 provider. Please migrate to the new OIDC compatible provider to use this feature",
"code": "feature_requires_oidc_provider"
}{
"shortMessage": "not a Progressive Sign Up instance",
"longMessage": "<feature> can only be used in instances that migrated to Progressive Sign Up. This feature is deprecated, please contact support if you need assistance.",
"code": "feature_requires_progressive_sign_up"
}{
"shortMessage": "not implemented",
"longMessage": "Feature `<feature>` is not available yet",
"code": "feature_not_implemented"
}{
"shortMessage": "",
"code": "form_already_exists",
"meta": {
"name": "param"
}
}
FormAtLeastOneOptionalParameterMissing signifies an error when at least one optional parameter must be provided
{
"shortMessage": "at least one parameter must be provided",
"longMessage": "at least one of `<parameters>` must be provided",
"code": "form_param_missing",
"meta": {
"names": "paramnames"
}
}
FormDisabledParameterValue signifies an error when the given parameter has an invalid value because it is not enabled in the settings
{
"shortMessage": "is disabled",
"longMessage": "<value> is disabled. Please verify you're using the correct instance, or see our docs to learn how to enable this value.",
"code": "form_param_value_disabled",
"meta": {
"name": "param"
}
}{
"shortMessage": "Date values must not be in the future.",
"longMessage": "Date values must not be in the future.",
"code": "form_disallow_future_date",
"meta": {
"name": "param"
}
}
FormDuplicateParameter signifies an error when a duplicate parameter is found in a form
{
"shortMessage": "is duplicate",
"longMessage": "<param> included multiple times. There should only be one.",
"code": "form_param_duplicate",
"meta": {
"name": "param"
}
}
FormDuplicateParameterValue signifies an error when a value has been provided multiple times
{
"shortMessage": "duplicate values",
"longMessage": "<value> contains duplicate values",
"code": "form_param_duplicate",
"meta": {
"name": "param"
}
}
FormIdentifierExists signifies an error when given identifier already exists
{
"shortMessage": "",
"code": "form_identifier_exists",
"meta": {
"name": "param"
}
}
FormIdentifierExistsWithAnotherAccount signifies an error when given identifier already exists.
This is used to signal to a user that the identifier, phone number, is already associated with another account and should remove it from the other account.
{
"shortMessage": "",
"code": "form_identifier_exists",
"meta": {
"name": "param"
}
}
FormIdentifierNotFound signifies an error when a required identifier is not found
{
"shortMessage": "",
"code": "form_identifier_not_found",
"meta": {
"name": "param"
}
}
FormIncorrectCode signifies an error when the given code is incorrect
{
"shortMessage": "is incorrect",
"longMessage": "Incorrect code",
"code": "form_code_incorrect",
"meta": {
"name": "param"
}
}{
"shortMessage": "is incorrect",
"longMessage": "Incorrect signature",
"code": "form_incorrect_signature"
}{
"shortMessage": "is invalid",
"longMessage": "<parameter> must be a valid email address.",
"code": "form_param_format_invalid",
"meta": {
"name": "param"
}
}{
"shortMessage": "invalid email addresses",
"longMessage": "The following email addresses are invalid: <emailAddresses>",
"code": "form_param_format_invalid",
"meta": {
"emailaddresses": "invalidemailaddresses"
}
}
FormInvalidEncodingParameterValue signifies an error when the given parameter has an invalid encoding
{
"shortMessage": "invalid character encoding",
"longMessage": "<param> contains invalid UTF-8 characters",
"code": "form_param_value_invalid",
"meta": {
"name": "param"
}
}
FormInvalidParameterFormat signifies an error when the given parameter has an invalid format
{
"shortMessage": "",
"code": "form_param_format_invalid",
"meta": {
"name": "param"
}
}
FormInvalidParameterFormatBCP47 signifies an error when the given parameter does not match the BCP-47 format
{
"shortMessage": "is invalid",
"longMessage": "<parameter> must be a valid BCP-47 language tag.",
"code": "form_param_format_invalid",
"meta": {
"name": "param"
}
}
FormInvalidParameterValue signifies an error when the given parameter has an invalid value
{
"shortMessage": "is invalid",
"longMessage": "<value> does not match one of the allowed values for parameter <param>",
"code": "form_param_value_invalid",
"meta": {
"name": "param"
}
}{
"shortMessage": "is invalid",
"longMessage": "<param> is invalid. Must be not empty",
"code": "form_param_value_invalid",
"meta": {
"name": "param"
}
}
FormInvalidParameterValueWithAllowed signifies an error when the given parameter has an invalid value.
The difference with FormInvalidParameterValue is that this error also includes the allowed values
{
"shortMessage": "is invalid",
"longMessage": "<value> does not match the allowed values for parameter <param>. Allowed values: <allowedValues>",
"code": "form_param_value_invalid",
"meta": {
"name": "param"
}
}
FormInvalidPasswordLengthTooLong signifies an error when the password is invalid because of its length
{
"shortMessage": "",
"code": "form_password_length_too_long",
"meta": {
"name": "param"
}
}
FormInvalidPasswordLengthTooShort signifies an error when the password is invalid because of its length
{
"shortMessage": "",
"code": "form_password_length_too_short",
"meta": {
"name": "param"
}
}{
"shortMessage": "Passwords must contain at least one lowercase character.",
"longMessage": "Passwords must contain at least one lowercase character.",
"code": "form_password_no_lowercase",
"meta": {
"name": "param"
}
}{
"shortMessage": "Passwords must contain at least one number.",
"longMessage": "Passwords must contain at least one number.",
"code": "form_password_no_number",
"meta": {
"name": "param"
}
}{
"shortMessage": "",
"code": "form_password_no_special_char",
"meta": {
"name": "param"
}
}{
"shortMessage": "Given password is not strong enough.",
"longMessage": "Given password is not strong enough.",
"code": "form_password_not_strong_enough"
}{
"shortMessage": "Passwords must contain at least one uppercase character.",
"longMessage": "Passwords must contain at least one uppercase character.",
"code": "form_password_no_uppercase",
"meta": {
"name": "param"
}
}
FormInvalidPasswordSizeInBytesExceeded signifies that the size in bytes was exceeded.
Note that the maximum character length constraint may fail to detect this case,
if multi-byte characters are included in the password.
For example, bcrypt limit https://cs.opensource.google/go/x/crypto/+/refs/tags/v0.8.0:bcrypt/bcrypt.go;l=87
{
"shortMessage": "Your password is too long. Please use a shorter one.",
"longMessage": "Your password is too long. Please use a shorter one.",
"code": "form_password_size_in_bytes_exceeded",
"meta": {
"name": "param"
}
}{
"shortMessage": "is invalid",
"longMessage": "<parameter> must be a valid phone number according to E.164 international standard.",
"code": "form_param_format_invalid",
"meta": {
"name": "param"
}
}{
"shortMessage": "invalid format",
"longMessage": "<param> must contain a datetime specified in RFC3339 format (e.g. `2022-10-20T10:00:27.645Z`).",
"code": "form_param_invalid_time",
"meta": {
"name": "param"
}
}
FormInvalidTypeParameter signifies an error when a form parameter has the wrong type
{
"shortMessage": "is invalid",
"longMessage": "`<param>` must be a `<paramType>`.",
"code": "form_param_type_invalid",
"meta": {
"name": "param"
}
}
FormInvalidUsernameCharacter signifies an error when the given username does not match username regex
{
"shortMessage": "",
"code": "form_username_invalid_character",
"meta": {
"name": "param"
}
}
FormInvalidUsernameLength signifies an error when the given username does not have required length
{
"shortMessage": "",
"code": "form_username_invalid_length",
"meta": {
"name": "param"
}
}
FormInvalidUsernameNeedsNonNumberCharCode signifies an error when the given username does not match username regex
{
"shortMessage": "",
"code": "form_username_needs_non_number_char",
"meta": {
"name": "param"
}
}
FormInvalidWeb3WalletAddress signifies an error when the given web3 wallet address is invalid
{
"shortMessage": "is invalid",
"longMessage": "<parameter> must be a valid web3 wallet address.",
"code": "form_param_format_invalid",
"meta": {
"name": "param"
}
}
FormDisabledParameterValue signifies an error when the legal consent value has not been filled
{
"shortMessage": "legal not accepted",
"longMessage": "Legal consent must be accepted in order to continue.",
"code": "legal_not_accepted",
"meta": {
"name": "param"
}
}
FormMaximumParametersExceeded signifies an error when more than 100 of the same param is included.
{
"shortMessage": "",
"longMessage": "<param> is included more than the maximum of 100 times.",
"code": "form_param_duplicate",
"meta": {
"name": "param"
}
}
FormMetadataInvalidType signifies an error when the given metadata is not a valid key-value object
{
"shortMessage": "",
"code": "form_param_value_invalid",
"meta": {
"name": "param"
}
}
FormMissingConditionalParameter signifies an error when required parameter based on conditions is missing
{
"shortMessage": "is missing",
"longMessage": "`<param>` is required when `<leftCondition>` is `<rightCondition>`.",
"code": "form_conditional_param_missing"
}
FormMissingConditionalParameterOnExistence signifies an error when parameter is required because of the existence of another
{
"shortMessage": "is missing",
"longMessage": "`<missingParam>` is required when `<conditionalParam>` is present.",
"code": "form_conditional_param_missing",
"meta": {
"name": "missingparam"
}
}
FormMissingParameter signifies an error when an expected form parameter is missing
{
"shortMessage": "is missing",
"longMessage": "<param> must be included.",
"code": "form_param_missing",
"meta": {
"name": "param"
}
}
FormMissingResource signifies an error when the form parameter is referring to a missing resource
{
"shortMessage": "is missing",
"longMessage": "The resource associated with the supplied <param> was not found.",
"code": "form_resource_not_found",
"meta": {
"name": "param"
}
}{
"shortMessage": "is invalid",
"longMessage": "New password cannot be the same as the current password.",
"code": "form_new_password_matches_current",
"meta": {
"name": "param"
}
}
FormNilParameter signifies an error when a nil parameter is found in a form
{
"shortMessage": "",
"code": "form_param_nil",
"meta": {
"name": "param"
}
}
FormNilParameterWithCustomText signifies an error when a nil parameter is found in a form.
This variant also accepts a custom text to be displayed.
{
"shortMessage": "",
"code": "form_param_nil",
"meta": {
"name": "param"
}
}
FormNotAllowedToDisableDefaultSecondFactor signifies an error when trying to disable the default flag from a second-factor
{
"shortMessage": "The default second factor method can only be changed by assigning another method as the default.",
"longMessage": "The default second factor method can only be changed by assigning another method as the default.",
"code": "form_disable_default_second_factor_not_allowed",
"meta": {
"name": "param"
}
}
FormParameterArraySizeExceeded signifies an error when the given array exceeds the maximum allowed size
{
"shortMessage": "exceeds maximum size",
"longMessage": "<parameter> should not exceed %d items.",
"code": "form_param_array_size_exceeded",
"meta": {
"name": "param"
}
}
FormParameterDeprecated signifies an error when a form parameter has been
deprecated and is no longer accepted by the endpoint. The resolution argument
can describe the recommended replacement (e.g. a different endpoint) and is
appended to the long message when non-empty.
{
"shortMessage": "is deprecated",
"longMessage": "is deprecated",
"code": "form_param_deprecated",
"meta": {
"name": "param"
}
}
FormParameterMaxLengthExceeded signifies an error when the given param value exceeds the maximum allowed length
{
"shortMessage": "exceeds maximum length",
"longMessage": "<parameter> should not exceed %d characters.",
"code": "form_param_max_length_exceeded",
"meta": {
"name": "param"
}
}
FormParameterNotAllowedConditionally signifies an error when parameter is not allowed based on condition
{
"shortMessage": "is not allowed",
"longMessage": "`<param>` isn't allowed when `<leftCondition>` is <rightCondition>.",
"code": "form_conditional_param_disallowed",
"meta": {
"name": "param"
}
}
FormParameterNotAllowedIfAnotherParameterIsPresent signifies an error when a parameter is present but
is not allowed because another parameter is also present
{
"shortMessage": "is not allowed",
"longMessage": "`<notAllowedParam>` isn't allowed when `<existingParam>` is present.",
"code": "form_conditional_param_disallowed",
"meta": {
"name": "notallowedparam"
}
}
FormParameterSizeTooLarge signifies an error when a parameter exceeds the max allowed size
{
"shortMessage": "",
"code": "form_param_exceeds_allowed_size",
"meta": {
"name": "param"
}
}
FormParameterValueConflict signifies an error when two parameters that name
the same underlying value — typically a legacy name and the name that
replaces it — are both present but carry different values.
Either name is accepted on its own and both may be sent together as long as they agree, so this is a conflict between the two values rather than one parameter disallowing the other. Use [FormParameterNotAllowedIfAnotherParameterIsPresent] for that case.
{
"shortMessage": "conflicting values",
"longMessage": "`<param>` and `<otherParam>` refer to the same value, so they must match when both are sent.",
"code": "form_param_value_conflict",
"meta": {
"name": "param"
}
}{
"shortMessage": "Value too large",
"longMessage": "The value of <param> can't be greater than %d",
"code": "form_param_value_too_large",
"meta": {
"name": "param"
}
}
FormPasswordCompromised signifies an error when the chosen password has been found in the pwned list
{
"shortMessage": "",
"longMessage": "Your password may be compromised. To protect your account, please continue with an alternative sign-in method. You will be required to reset your password after signing in.",
"code": "form_password_compromised",
"meta": {
"name": "param"
}
}
FormPasswordDigestInvalid signifies an error when the provided password_digest is not valid for the provided password_hasher
{
"shortMessage": "",
"code": "form_password_digest_invalid_code",
"meta": {
"name": "param"
}
}
FormPasswordIncorrect signifies an error when given password is incorrect
{
"shortMessage": "Password is incorrect. Try again, or use another method.",
"longMessage": "Password is incorrect. Try again, or use another method.",
"code": "form_password_incorrect",
"meta": {
"name": "param"
}
}
FormPasswordMatchesIdentifier signifies an error when the chosen password
is identical to one of the account's identifiers (email address, phone
number or username).
{
"shortMessage": "Password cannot match your email address, phone number or username. For account safety, please use a different password.",
"longMessage": "Password cannot match your email address, phone number or username. For account safety, please use a different password.",
"code": "form_password_matches_identifier",
"meta": {
"name": "param"
}
}
FormPasswordOrIdentifierIncorrect signifies an error when given password
is incorrect or given identifier does not match an existing account, but does
not return which is incorrect. This is used with enumeration protection.
{
"shortMessage": "",
"code": "form_password_or_identifier_incorrect"
}
FormPasswordValidationFailed signifies a generic error when the password validation failed
{
"shortMessage": "Incorrect password. Please try again.",
"longMessage": "Incorrect password. Please try again.",
"code": "form_password_validation_failed",
"meta": {
"name": "param"
}
}{
"shortMessage": "is invalid",
"longMessage": "PKCE is required for OAuth clients without a secret",
"code": "form_public_client_requires_pkce",
"meta": {
"name": "param"
}
}
FormPwnedPassword signifies an error when the chosen password has been found in the pwned list
{
"shortMessage": "",
"code": "form_password_pwned",
"meta": {
"name": "param"
}
}
FormUnknownParameter signifies an error when an unexpected parameter is found in a form
{
"shortMessage": "is unknown",
"longMessage": "<param> is not a valid parameter for this request.",
"code": "form_param_unknown",
"meta": {
"name": "param"
}
}
FormUnknownParameterDueToDisabledFeature signifies an error when an unexpected parameter is found in a form due to a disabled feature
{
"shortMessage": "is unknown",
"longMessage": "<param> is not a valid parameter for this request.<possibleResolution>",
"code": "form_param_unknown",
"meta": {
"name": "param"
}
}
FormUnverifiedIdentification signifies an error when the identification included in the form is unverified
{
"shortMessage": "is unverified",
"longMessage": "This identification needs to be verified before you can perform this action.",
"code": "form_verification_needed",
"meta": {
"name": "param"
}
}
FormUsernameCannotBePhoneNumber signifies an error when the given username
is in canonical E.164 phone-number format. This is rejected regardless of
the configured username character set so that the value remains reserved
for the phone-number identifier and avoids ambiguity at sign-in.
{
"shortMessage": "",
"longMessage": "<parameter> cannot be a phone number. Please choose a different username.",
"code": "form_username_cannot_be_phone_number",
"meta": {
"name": "param"
}
}
FormValidationFailed converts validator.ValidationErrors to Error.
{
"shortMessage": "is invalid",
"longMessage": "<sanitizedField> is invalid",
"code": "form_param_value_invalid",
"meta": {
"name": "sanitizedfield"
}
}{
"shortMessage": "device attestation challenge client mismatch",
"longMessage": "The device attestation challenge provided is not valid for the client.",
"code": "device_attestation_challenge_client_mismatch"
}{
"shortMessage": "device attestation is misconfigured",
"longMessage": "Device attestation is misconfigured for this instance.",
"code": "device_attestation_misconfigured"
}{
"shortMessage": "device attestation not configured",
"longMessage": "Device attestation is not configured for this instance.",
"code": "device_attestation_not_configured"
}{
"shortMessage": "unsupported native client platform",
"longMessage": "Device attestation is not supported for the client platform.",
"code": "device_attestation_unsupported_platform"
}{
"shortMessage": "device attestation verification failed",
"longMessage": "Failed to verify the provided device attestation.",
"code": "device_attestation_verification_failed"
}{
"shortMessage": "Action blocked",
"longMessage": "This action was detected as suspicious and has been blocked. If you believe this was a mistake, please contact support.",
"code": "action_blocked"
}{
"shortMessage": "Device blocked",
"longMessage": "This device was detected as suspicious and has been blocked. It will no longer be able to perform actions. If you believe this was by mistake, please contact support.",
"code": "device_blocked"
}{
"shortMessage": "Unusual activity was detected",
"longMessage": "Unusual activity was detected. Please try again later or contact our support if you continue to experience issues.",
"code": "captcha_invalid"
}{
"shortMessage": "Sign up rate limit exceeded",
"longMessage": "The sign up rate limit was exceeded. Please try a different method or contact our support if you continue to experience issues.",
"code": "signup_rate_limit_exceeded"
}{
"shortMessage": "invalid device attestation assertion",
"longMessage": "The device attestation assertion provided is invalid.",
"code": "invalid_device_attestation_assertion"
}{
"shortMessage": "invalid device attestation challenge",
"longMessage": "The device attestation challenge provided is either invalid or has expired.",
"code": "invalid_device_attestation_challenge"
}{
"shortMessage": "protect check already resolved",
"longMessage": "This protect check has already been completed and cannot be resolved again.",
"code": "protect_check_already_resolved"
}{
"shortMessage": "Protect check required",
"longMessage": "A Protect check is required before this action can continue.",
"code": "requires_protect_check",
"meta": {
"protect_check": "protectcheck"
}
}{
"shortMessage": "Device attestation is required",
"longMessage": "A valid device attestation could not be found for the client.",
"code": "requires_device_attestation"
}{
"shortMessage": "Resource is gone",
"longMessage": "The requested resource no longer exists.",
"code": "gone"
}{
"shortMessage": "Google One Tap token is invalid",
"longMessage": "The provided Google One Tap token is invalid. Make sure you're using a valid token generated by Google.",
"code": "google_one_tap_token_invalid"
}Identifications
IdentificationNotFound signifies an error when comm is not found
{
"shortMessage": "Resource not found",
"longMessage": "Resource not found",
"code": "resource_not_found"
}{
"shortMessage": "",
"longMessage": "Your <sanitizedAttributeType> is immutable and cannot be modified or removed.",
"code": "immutable_attribute_modification_not_allowed"
}
LastIdentificationDeletionFailed signifies an error when trying to delete the last identification associated with a user
{
"shortMessage": "Deletion failed",
"longMessage": "You cannot delete your last identification.",
"code": "identification_deletion_failed"
}{
"shortMessage": "Update failed",
"longMessage": "You cannot set your last identification as second factor.",
"code": "identification_update_failed"
}{
"shortMessage": "",
"longMessage": "You are required to maintain at least one <sanitizedIdentType> in your account at all times",
"code": "last_required_identification_deletion_failed"
}{
"shortMessage": "Cannot connect account",
"longMessage": "This account cannot be connected because its <sanitizedAttributeType> does not match your existing <sanitizedAttributeType>.",
"code": "oauth_connection_blocked_by_immutable_attribute"
}{
"shortMessage": "second factor deletion not allowed",
"longMessage": "You are required to maintain at least one two-step verification method in your account at all times",
"code": "second_factor_deletion_not_allowed"
}{
"shortMessage": "too many unverified contacts",
"longMessage": "There are too many unverified contacts for this user.",
"code": "too_many_unverified_identifications"
}{
"shortMessage": "Update failed",
"longMessage": "Cannot update second factor attributes for unverified identification",
"code": "identification_update_second_factor_unverified"
}{
"shortMessage": "Image decode error",
"longMessage": "The image could not be decoded. Please ensure the image is valid and try again.",
"code": "request_body_invalid"
}{
"shortMessage": "Image not found",
"longMessage": "Image not found",
"code": "image_not_found"
}
ImageTooLarge signifies an error when the image being uploaded is too large to handle.
{
"shortMessage": "Image too large",
"longMessage": "The image being uploaded is more than 10MB. Please choose a smaller one.",
"code": "image_too_large"
}{
"shortMessage": "Unsupported image type",
"longMessage": "'<imageType>' images are not currently supported. Please consult the API documentation for more information.",
"code": "request_body_invalid"
}
RequestWithoutImage signifies an error when no image was present in the request.
{
"shortMessage": "Image file missing",
"longMessage": "There was no image file present in the request",
"code": "form_param_missing"
}Instance Keys
InstanceKeyRequired signifies an error when no instance keys exist
{
"shortMessage": "Key required",
"longMessage": "Please generate at least one instance key",
"code": "instance_key_required"
}Instances
InstanceTypeInvalid signifies an error when a request cannot be applied to the given instance
{
"shortMessage": "This request isn't valid for this instance type.",
"longMessage": "This request isn't valid for this instance type.",
"code": "instance_type_invalid"
}{
"shortMessage": "Bad request",
"longMessage": "Bad request",
"code": "bad_request"
}{
"shortMessage": "",
"code": "bad_request"
}
403 - quota exceeded
{
"shortMessage": "Quota exceeded",
"longMessage": "Quota exceeded, you have reached your limit.",
"code": "quota_exceeded"
}
409 - resource locked
{
"shortMessage": "resource busy",
"longMessage": "This resource is currently being modified by another request. Please try again.",
"code": "resource_locked"
}{
"shortMessage": "Too many requests",
"longMessage": "Too many requests, retry later",
"code": "too_many_requests",
"meta": "{\"ResetsIn\": resetsIn}"
}
Unexpected is used for all unexpected errors
It unwraps the error chain to check if an API error was wrapped,
and returns that instead of creating a 500 error
{
"shortMessage": "Oops, an unexpected error occurred",
"longMessage": "There was an internal error on our servers. We've been notified and are working on fixing it.",
"code": "internal_clerk_error"
}Invitations
InvitationAccountAlreadyExists denotes an error when there is an existing
user identification with the same email as the invitation.
{
"shortMessage": "account exists",
"longMessage": "An account already exists for this invitation. Sign in instead.",
"code": "invitation_account_exists"
}
InvitationAlreadyAccepted denotes an error when someone tries to use
an invitation which is already accepted.
{
"shortMessage": "Invitation is already accepted, try signing in instead.",
"longMessage": "Invitation is already accepted, try signing in instead.",
"code": "invitation_already_accepted"
}{
"shortMessage": "identification not found",
"longMessage": "This invitation refers to a non-existing identification.",
"code": "invitation_account_not_exists"
}
InvitationNotFound denotes an error when there is no invitation with
the given id
{
"shortMessage": "not found",
"longMessage": "No invitation was found with id <invitationID>.",
"code": "resource_not_found"
}
InvitationsNotSupportedInInstance denotes an error when user is
trying to create an invitation on an instance that doesn't support it
{
"shortMessage": "Invitations are only supported on instances that accept email addresses.",
"longMessage": "Invitations are only supported on instances that accept email addresses.",
"code": "invitations_not_supported"
}
RevokedInvitation denotes an error when the given invitation token
does not correspond to any invitations, which means that the invitation
has been removed.
{
"shortMessage": "The invitation was revoked.",
"longMessage": "The invitation was revoked.",
"code": "revoked_invitation"
}Jwt Templates
JWTTemplateNotFound signifies an error when a JWT template was not found by the provided attribute
{
"shortMessage": "JWT template not found",
"longMessage": "No JWT template exists with <attribute>: <val>",
"code": "resource_not_found"
}{
"shortMessage": "approval token consumed",
"longMessage": "The approval token has already been used.",
"code": "approval_token_consumed"
}{
"shortMessage": "approval token expired",
"longMessage": "The approval token has expired. Please request a new email link.",
"code": "approval_token_expired"
}{
"shortMessage": "approval token invalid",
"longMessage": "The approval token is invalid.",
"code": "approval_token_invalid"
}Network
GatewayTimeout signifies an error when a 3rd party service takes too long to respond.
{
"shortMessage": "Gateway Timeout",
"longMessage": "A request to a 3rd party service timed out",
"code": "gateway_timeout"
}{
"shortMessage": "custom OAuth provider cannot use discovery URL",
"longMessage": "The custom OAuth provider cannot use the discovery URL. Please provide the necessary configuration manually.",
"code": "custom_oauth_provider_cannot_use_discovery_url",
"meta": {
"name": "discovery_url"
}
}{
"shortMessage": "issuer mismatch in custom OAuth provider discovery URL",
"longMessage": "The issuer in the discovery URL (<url>) does not match the issuer returned in the configuration (<issuer>).",
"code": "custom_oauth_provider_discovery_issuer_mismatch",
"meta": {
"name": "discovery_url"
}
}{
"shortMessage": "error retrieving OAuth response from provider's discovery URL",
"longMessage": "An error was encountered when attempting to retrieve metadata from the oauth url %q: %q",
"code": "custom_oauth_provider_discovery_server_retrieval_error",
"meta": {
"name": "discovery_url"
}
}
ExternalAccountEmailAddressVerificationRequired signifies an error when the external account requires email address verification
{
"shortMessage": "Email address verification required",
"longMessage": "Your associated email address is required to be verified, because it was initially created as unverified.",
"code": "external_account_email_address_verification_required"
}{
"shortMessage": "Missing refresh token",
"longMessage": "We cannot refresh your OAuth access token because the server didn't provide a refresh token. Please re-connect your account.",
"code": "external_account_missing_refresh_token"
}
ExternalAccountNotFound signifies an error when the external account of the oauth callback is not found
NOTE: This legacy error message and code is misleading. We also throw this error in transfer flows
where an external account was created, but no corresponding user has yet been created.
{
"shortMessage": "Invalid external account",
"longMessage": "The External Account was not found.",
"code": "external_account_not_found"
}
InvalidOAuthCallback signifies an error when the form of OAuth callback is invalid
{
"shortMessage": "Invalid OAuth callback",
"longMessage": "invalid form for oauth_callback",
"code": "oauth_callback_invalid"
}
MisconfiguredOAuthProvider signifies an error when there is a misconfiguration for an OAuth provider
{
"shortMessage": "Misconfigured OAuth provider",
"longMessage": "Misconfigured OAuth provider. Please make sure you have set it correctly",
"code": "misconfigured_oauth_provider"
}
NonAuthenticatableOauthProvider signifies an error when an oauth flow step is attempted for a provider that is not
enabled for authentication.
{
"shortMessage": "",
"longMessage": "%v OAuth is not supported for authentication. Please contact us if you think this error should not appear.",
"code": "oauth_non_authenticatable_provider"
}{
"shortMessage": "",
"longMessage": "You did not grant access to your <providerName> account",
"code": "oauth_access_denied"
}
OAuthAccountAlreadyConnected signifies an error when an OAuth account if already connected for a specific provider
{
"shortMessage": "Already connected",
"longMessage": "Another account is already connected for this particular provider (<providerTitle>)",
"code": "oauth_account_already_connected"
}
OAuthAdditionalScopesNotSupportedForSharedCredentials signifies an error when
a caller requests additional OAuth scopes for a provider that is using
Clerk's shared development credentials. Requesting extra scopes requires
configuring custom OAuth credentials for the provider.
{
"shortMessage": "Additional scopes not supported with shared credentials",
"longMessage": "Requesting additional OAuth scopes is not supported while using Clerk's shared development credentials. Configure custom OAuth credentials for this provider to request additional scopes.",
"code": "oauth_additional_scopes_not_supported_for_shared_credentials"
}
OAuthConfigMissing signifies an error when an application does not have
SSO credentials set, for a particular SSO provider.
{
"shortMessage": "",
"longMessage": "The application does not have <provider> OAuth keys set in its settings.",
"code": "oauth_config_missing"
}{
"shortMessage": "Fetch user error",
"longMessage": "Fetch user error",
"code": "oauth_fetch_user_error"
}
OAuthIdentificationClaimed signifies an error when the requested oauth identification is already claimed by another user
{
"shortMessage": "Identification claimed by another user",
"longMessage": "The email address associated with this OAuth account is already claimed by another user.",
"code": "oauth_identification_claimed"
}{
"shortMessage": "",
"longMessage": "Your <providerName> account configuration is invalid. Make sure you register this endpoint in the list of allowed callback URLs.",
"code": "redirect_uri_mismatch"
}{
"shortMessage": "malformed redirect uri provided",
"longMessage": "malformed redirect uri provided",
"code": "redirect_uri_mismatch"
}{
"shortMessage": "Missing OAuth access token",
"longMessage": "OAuth access token is missing",
"code": "oauth_missing_access_token"
}{
"shortMessage": "Cannot refresh OAuth access token",
"longMessage": "The current access token has expired and we cannot refresh it, because the authorization server hasn't provided us with a refresh token",
"code": "oauth_missing_refresh_token"
}{
"shortMessage": "",
"longMessage": "Single-sign on with <providerTitle> OAuth provider is not enabled in the instance settings.",
"code": "oauth_provider_not_enabled"
}
OAuthSharedCredentialsNotSupported signifies an error when an OAuth provider uses our shared credentials, but those are not supported anymore.
{
"shortMessage": "Shared credentials not supported",
"longMessage": "Shared credentials are no longer supported for this provider. Please update via the Clerk Dashboard.",
"code": "oauth_shared_credentials_not_supported"
}{
"shortMessage": "Token exchange error",
"longMessage": "Token exchange error",
"code": "oauth_token_exchange_error"
}
OAuthUnregisteredRedirectURI signifies that the redirect_uri on an OAuth 2.0
authorization request does not exactly match any URI registered for the
application. It shares the status and code of [OAuthMalformedRedirectURI] so
existing clients keep handling it the same way.
{
"shortMessage": "invalid redirect uri provided",
"longMessage": "The redirect_uri does not exactly match a redirect URI registered for this OAuth application.",
"code": "redirect_uri_mismatch"
}
UnsupportedOauthProvider signifies an error when an instance tries to enable
an OAuth external provider which is not supported.
{
"shortMessage": "",
"longMessage": "%v OAuth is not supported. Please contact us if you think this error should not appear.",
"code": "oauth_unsupported_provider"
}Oauth2 Idp
OAuthFetchUserInfo signifies an error when user info cannot be retrieved with the access token
{
"shortMessage": "unable to fetch user info",
"longMessage": "Unable to fetch user info. Check if access token is present and valid.",
"code": "oauth_fetch_user_error"
}Organizations
400 - User with given identifier is already a member of the organization and cannot be added again
{
"shortMessage": "already a member",
"longMessage": "<user> is already a member of the organization.",
"code": "already_a_member_in_organization"
}{
"shortMessage": "not found",
"longMessage": "Default organization role not found",
"code": "resource_not_found"
}
422 - Returned when a user cannot join (or be added to) an organization because either the user already belongs to an exclusive organization or the target organization is exclusive and the user has other memberships.
{
"shortMessage": "exclusive organization membership",
"longMessage": "User cannot belong to multiple organizations because exclusive membership is enabled.",
"code": "exclusive_organization_membership"
}
422 - Returned when enabling exclusive_membership on an organization is rejected because the organization already has members who belong to other organizations in the same instance. Enabling the flag would retroactively violate the invariant for those pre-existing members, so the flip is denied.
{
"shortMessage": "exclusive organization membership cannot be enabled",
"longMessage": "Exclusive membership cannot be enabled because existing members of this organization belong to other organizations. Remove their other memberships before enabling exclusive membership.",
"code": "exclusive_organization_membership_existing_members"
}{
"shortMessage": "not allowed",
"longMessage": "`force_organization_selection` cannot be enabled when organizations are disabled. Please enable organizations first.",
"code": "force_organization_selection_not_allowed_when_organizations_disabled"
}{
"shortMessage": "email invitations not supported",
"longMessage": "This organization doesn't support email invitations. Please contact support to enable this feature.",
"code": "invitations_not_supported_in_organization"
}{
"shortMessage": "missing permission",
"longMessage": "Current user is missing an organization permission.",
"code": "missing_organization_permission",
"meta": {
"permissions": "permissions"
}
}
403 - Only for organization members Deprecated: This error reveals the existence of an organization to an unauthorized user. Use OrganizationNotFoundOrUnauthorized instead, and ensure other pathways that error when the organization isn't found also use OrganizationNotFoundOrUnauthorized
{
"shortMessage": "not a member",
"longMessage": "Current user is not a member of the organization. Only organization members can perform this action.",
"code": "not_a_member_in_organization"
}{
"shortMessage": "admin delete not enabled",
"longMessage": "Deletion by admin is not enabled for this organization.",
"code": "organization_admin_delete_not_enabled"
}{
"shortMessage": "this organization already has an SSO connection",
"longMessage": "This organization already has an SSO connection.",
"code": "organization_already_has_sso_connection",
"meta": {
"name": "organization_id"
}
}{
"shortMessage": "organizaton domain already exists",
"longMessage": "This domain is already used by another organization.",
"code": "organization_domain_already_exists",
"meta": {
"name": "param"
}
}{
"shortMessage": "organization domain already exists",
"longMessage": "This domain is already used by your organization.",
"code": "organization_domain_already_exists_same_organization",
"meta": {
"name": "param"
}
}{
"shortMessage": "blocked email domain",
"longMessage": "This is a blocked email provider domain. Please use a different one.",
"code": "organization_domain_blocked",
"meta": {
"name": "param"
}
}{
"shortMessage": "common email domain",
"longMessage": "This is a common email provider domain. Please use a different one.",
"code": "organization_domain_common",
"meta": {
"name": "param"
}
}{
"shortMessage": "organization domain enrollment mode invalid",
"longMessage": "The domain %q is not configured for <domain> enrollment. Set the domain's enrollment mode to <requiredMode> before using it here.",
"code": "organization_domain_enrollment_mode_invalid",
"meta": {
"name": "param"
}
}{
"shortMessage": "organization enrollment mode not enabled",
"longMessage": "Enrollment mode <enrollmentMode> is not enabled for this instances's organizations.",
"code": "organization_domain_enrollment_mode_not_enabled"
}{
"shortMessage": "domain used for organization enrollment",
"longMessage": "This domain is already used for organization enrollment with verified domains. Please use a different one.",
"code": "organization_domain_exists_for_enrollment"
}{
"shortMessage": "domain exists for an organization enterprise connection",
"longMessage": "This domain is already used for your organization’s SSO. Please use a different one.",
"code": "organization_domain_exists_for_enterprise_connection"
}{
"shortMessage": "cannot delete last verified domain",
"longMessage": "This is the organization's only verified domain. Organizations must keep at least one verified domain, so it can't be deleted.",
"code": "organization_domain_last_verified_cannot_delete"
}{
"shortMessage": "Organization domain mismatch",
"longMessage": "The provided email address doesn't match the organization domain name.",
"code": "organization_domain_mismatch",
"meta": {
"name": "param"
}
}{
"shortMessage": "organization domain not verified",
"longMessage": "The domain %q is not a verified domain of this organization. Verify ownership of the domain before using it here.",
"code": "organization_domain_ownership_not_verified",
"meta": {
"name": "param"
}
}{
"shortMessage": "organization domains quota exceeded",
"longMessage": "You have reached your limit of %d domains per organization.",
"code": "organization_domain_quota_exceeded"
}{
"shortMessage": "organization domains not enabled",
"longMessage": "This instance does not have domains enabled for organizations.",
"code": "organization_domains_not_enabled"
}{
"shortMessage": "invitation has already been accepted",
"longMessage": "This invitation has already been accepted. Sign in instead.",
"code": "organization_invitation_already_accepted"
}{
"shortMessage": "email address already exists",
"longMessage": "The email address in this invitation already exists. If it belongs to you, try signing in instead.",
"code": "organization_invitation_identification_already_exists"
}{
"shortMessage": "identification not found",
"longMessage": "User not found. If you don't have an account, sign up first to accept this invitation.",
"code": "organization_invitation_identification_not_exist"
}
404 - Invitation not found.
{
"shortMessage": "not found",
"longMessage": "No invitation found with id <invitationID>.",
"code": "organization_invitation_not_found"
}
404 - Invitation is not pending.
{
"shortMessage": "not pending",
"longMessage": "The organization invitation is not in the 'pending' status.",
"code": "organization_invitation_not_pending"
}{
"shortMessage": "organization invitation not unique",
"longMessage": "Organizations cannot have duplicate pending invitations for an email address.",
"code": "organization_invitation_not_unique"
}{
"shortMessage": "invitation has been revoked",
"longMessage": "This invitation has been revoked and cannot be used anymore.",
"code": "organization_invitation_revoked_code"
}{
"shortMessage": "organization invitation to deleted organization",
"longMessage": "This invitation refers to an organization that has been deleted.",
"code": "organization_invitation_to_deleted_organization"
}{
"shortMessage": "organization managed role operation disallowed",
"longMessage": "Managed roles cannot be set through the frontend API. Use the dashboard or backend API instead.",
"code": "form_param_value_invalid",
"meta": {
"name": "paramname"
}
}
OrganizationMemberLimitManagedByBilling returns an error when trying to update
the member limit for an organization that is on a seat-based billing plan
{
"shortMessage": "member limit managed by Billing",
"longMessage": "This organization's member limit is managed by their subscription. It cannot be edited directly.",
"code": "organization_member_limit_managed_by_billing",
"meta": {
"name": "max_allowed_memberships"
}
}{
"shortMessage": "cannot remove enterprise connection organization membership",
"longMessage": "Cannot remove an organization membership that is tied to an enterprise connection.",
"code": "organization_membership_enterprise_connection_cannot_remove"
}{
"shortMessage": "organization membership quota exceeded",
"longMessage": "You have reached your limit of %d organization memberships, including outstanding invitations.",
"code": "organization_membership_quota_exceeded"
}{
"shortMessage": "organization membership quota exceeded for sso per org",
"longMessage": "The organization you are trying to join is full. Please contact support.",
"code": "organization_membership_quota_exceeded_for_sso"
}{
"shortMessage": "membership role managed by directory sync",
"longMessage": "This membership is managed by a directory and cannot be changed manually.",
"code": "organization_membership_managed_by_scim"
}{
"shortMessage": "minimum organization permissions needed",
"longMessage": "There has to be at least one organization member with the minimum required permissions",
"code": "organization_minimum_permissions_needed"
}{
"shortMessage": "invalid organization name",
"longMessage": "The organization name %q is invalid: <name>",
"code": "form_param_value_invalid",
"meta": {
"name": "name"
}
}{
"shortMessage": "access denied",
"longMessage": "The organizations feature is not enabled for this instance. You can enable it at https://dashboard.clerk.com.",
"code": "organization_not_enabled_in_instance"
}
404 - Organization not found
WARNING: This is safe to use for endpoints where the caller is authorized to be
aware of every organization. But if the endpoint errors if the caller is not
authorized on the organization, do not use this, because it leaks the existence
of the organization! Use OrganizationNotFoundOrUnauthorized instead.
{
"shortMessage": "not found",
"longMessage": "Given organization not found.",
"code": "resource_not_found"
}
404 - Used for any case
{
"shortMessage": "not found or unauthorized",
"longMessage": "Given organization not found, or you don't have permission to access the organization",
"code": "organization_not_found_or_unauthorized"
}{
"shortMessage": "organization quota exceeded",
"longMessage": "You have reached your limit of %d organizations. You can remove the organization limit by upgrading to a paid plan or using a production instance.",
"code": "organization_quota_exceeded"
}{
"shortMessage": "not found",
"longMessage": "Organization role not found",
"code": "resource_not_found",
"meta": {
"name": "paramname"
}
}{
"shortMessage": "role is assigned to users",
"longMessage": "The role <roleKey> is assigned to one or more users. Please re-assign the role to the users to proceed.",
"code": "organization_role_on_set_assigned_to_user",
"meta": {
"rolekey": "rolekey"
}
}{
"shortMessage": "contact support",
"longMessage": "This reassignment affects %d memberships, contact support to complete this operation",
"code": "organization_role_set_reassignment_contact_support"
}{
"shortMessage": "reassignment mappings invalid",
"longMessage": "The role <roleKey> is invalid in the reassignment mappings. It must be present in the new role set.",
"code": "organization_role_set_reassignment_mappings_invalid",
"meta": {
"rolekey": "rolekey"
}
}{
"shortMessage": "reassignment mappings missing",
"longMessage": "The following roles are missing from the reassignment mappings: %s",
"code": "organization_role_set_reassignment_mappings_missing",
"meta": {
"rolekeys": "rolekeys"
}
}
403 - Organizations cannot be enabled for this workspace.
{
"shortMessage": "Organizations cannot be enabled for this workspace.",
"longMessage": "Organizations cannot be enabled for this workspace.",
"code": "organizations_cannot_be_enabled"
}{
"shortMessage": "cannot disable organizations",
"longMessage": "Cannot disable organizations because <reason>.",
"code": "organizations_disable_not_allowed"
}{
"shortMessage": "organization slugs not enabled",
"longMessage": "This instance does not have slugs enabled for organizations.",
"code": "organization_slugs_disabled"
}{
"shortMessage": "suggestion has already been accepted",
"longMessage": "This organization suggestion has already been accepted.",
"code": "organization_suggestion_already_accepted"
}{
"shortMessage": "organization has limited memberships",
"longMessage": "This feature is not supported because organization membership is limited. You can remove the limit by enabling unlimited memberships.",
"code": "organization_unlimited_membership_required"
}{
"shortMessage": "organization has limited memberships",
"longMessage": "This feature is not supported because organization membership is limited. You can remove the limit by upgrading your subscription plan.",
"code": "organization_unlimited_membership_required"
}
403 - Organization Creation Limit Exceeded
{
"shortMessage": "Organization Creation Limit Exceeded",
"longMessage": "You have exceeded the maximum number of organizations you can create.",
"code": "org_creation_limit_exceeded"
}{
"shortMessage": "personal accounts are not allowed",
"longMessage": "You must maintain at least one organization membership since personal accounts are not allowed on the application",
"code": "personal_accounts_not_allowed"
}{
"shortMessage": "migration in progress",
"longMessage": "Cannot modify role set while role reassignment is in progress. Please wait for the migration to complete.",
"code": "role_migration_in_progress"
}{
"shortMessage": "User has no passkeys",
"longMessage": "User has no passkeys registered for this account",
"code": "no_passkeys_found_for_user"
}{
"shortMessage": "authentication failed",
"longMessage": "Passkey authentication failed",
"code": "passkey_authentication_failure"
}{
"shortMessage": "passkey identification not verified",
"longMessage": "Passkey identification not verified. Registration is incomplete.",
"code": "passkey_identification_not_verified"
}{
"shortMessage": "is invalid",
"longMessage": "Invalid passkey public key credential",
"code": "passkey_invalid_public_key_credential",
"meta": {
"name": "param"
}
}{
"shortMessage": "invalid verification",
"longMessage": "Passkey verification contains invalid nonce",
"code": "passkey_invalid_verification"
}{
"shortMessage": "not registered",
"longMessage": "Passkey is not registered.",
"code": "passkey_not_registered"
}{
"shortMessage": "passkey quota exceeded",
"longMessage": "You have reached your limit of %d passkeys per account.",
"code": "passkey_quota_exceeded"
}{
"shortMessage": "PKCE verification failed",
"longMessage": "The provided code verifier does not match the prepared code challenge.",
"code": "pkce_verification_failed"
}{
"shortMessage": "Unsupported plan features",
"longMessage": "Some features are not supported in your current plan. Upgrade your subscription to unlock them.",
"code": "unsupported_subscription_plan_features",
"meta": {
"unsupportedfeatures": "unsupportedfeatures"
}
}Promo Codes
CheckoutPromoCodeInvalid is returned when the code a C2 typed at checkout
cannot be applied for any reason that the client should render as the single
"Invalid promo code" inline state: the code does not exist, is archived, its
parent discount's redemption window is not open, or the discount does not
target this checkout's price, period, or currency. The cause is deliberately
not disclosed so codes cannot be probed.
{
"shortMessage": "Invalid promo code",
"longMessage": "This promo code cannot be applied to this checkout",
"code": "checkout_promo_code_invalid",
"meta": {
"name": "paramname"
}
}
PromoCodeNotApplicableToCheckout is returned when the checkout itself cannot
carry a promo code (for example a seat-addition checkout, which reuses the
subscription item's already-applied discount), regardless of which code was
sent.
{
"shortMessage": "Promo code not applicable",
"longMessage": "A promo code cannot be applied to this checkout",
"code": "promo_code_not_applicable_to_checkout"
}
PromoCodeRedemptionLimitReached is returned when applying or confirming a
promo code whose max_redemptions slots are all taken by minted redemptions
or in-flight confirms. A slot can free up if an in-flight payment fails or
its confirm is abandoned, so unlike [CheckoutPromoCodeInvalid] this state is
distinguishable and potentially temporary.
{
"shortMessage": "Promo code limit reached",
"longMessage": "This promo code has reached its redemption limit",
"code": "promo_code_redemption_limit_reached",
"meta": {
"name": "paramname"
}
}Redirect Urls
InvalidRedirectURL signifies an error when a RedirectURL is in invalid format
{
"shortMessage": "Redirect url invalid",
"longMessage": "The provided redirect url is not in a valid format",
"code": "invalid_redirect_url"
}
ProhibitedRedirectURL signifies that the redirect url scheme is prohibited
{
"shortMessage": "Invalid URL scheme",
"longMessage": "The provided redirect url has a prohibited URL scheme",
"code": "prohibited_redirect_url"
}{
"shortMessage": "Redirect url does not belong to your domain",
"longMessage": "The provided redirect URL must belong to your instance's domain",
"code": "redirect_url_domain_mismatch"
}
RedirectURLMismatch signifies an error when the RedirectURL that was passed during an OAuth flow is not included in the redirect_urls whitelist for that instance.
{
"shortMessage": "Redirect url mismatch",
"longMessage": "The current redirect url passed in the sign in or sign up request does not match an authorized redirect URI for this instance. Review authorized redirect urls for your instance. <val>",
"code": "resource_missmatch"
}{
"shortMessage": "Redirect URL is not configured for this instance",
"longMessage": "Clerk could not complete satellite-domain authentication because redirect URL host %q is not configured for this production instance. This usually happens when a production Clerk instance is used from an unconfigured preview deployment. Use a configured primary or satellite domain, or use a development or staging Clerk instance for preview deployments.",
"code": "redirect_url_not_associated_with_instance",
"meta": {
"name": "redirect_url"
}
}{
"shortMessage": "bulk size exceeded",
"longMessage": "Parameters exceed the maximum allowed bulk processing size of %d.",
"code": "bulk_size_exceeded"
}{
"shortMessage": "invalid API version",
"longMessage": "Invalid Clerk API version: <reason>",
"code": "api_version_invalid"
}{
"shortMessage": "",
"longMessage": "<value> does not match one of the allowed values for parameter <param>",
"code": "invalid_query_parameter_value"
}
InvalidRequestBody signifies an error when the body of the request does not conform to the expected format
{
"shortMessage": "Request body invalid",
"longMessage": "The request body is invalid. Please consult the API documentation for more information.",
"code": "request_body_invalid"
}
MalformedRequestParameters signifies an error when the request parameters are malformed and result in parsing errors
{
"shortMessage": "Malformed request parameters",
"longMessage": "The request parameters are malformed and could not be parsed",
"code": "malformed_request_parameters"
}
MissingQueryParameter denotes that the required query parameter, param, was
not provided by the request.
{
"shortMessage": "",
"longMessage": "The query parameter '<param>' is missing from the request. Please consult the API documentation for more information.",
"code": "missing_query_parameter"
}
OriginHeaderMissing
{
"shortMessage": "Origin header missing",
"longMessage": "This request requires an Origin header to be set, but it is missing",
"code": "origin_missing"
}{
"shortMessage": "invalid secret key",
"longMessage": "The secret key given with this proxy request is invalid.",
"code": "proxy_request_invalid_secret_key"
}{
"shortMessage": "missing secret key",
"longMessage": "When using a proxy, it's required to also pass the instance secret key in the Clerk-Secret-Key header.",
"code": "proxy_request_missing_secret_key"
}{
"shortMessage": "Request body too large",
"longMessage": "The request body exceeds the maximum allowed size of %d bytes.",
"code": "request_body_too_large"
}
UnsupportedContentType signifies an error when provided content type is unsupported
{
"shortMessage": "Content-Type is unsupported",
"longMessage": "Content-Type <actual> is unsupported. You should use <expected> instead.",
"code": "unsupported_content_type"
}{
"shortMessage": "not found",
"longMessage": "No active SAML Connection found with id <connectionID>.",
"code": "saml_connection_active_not_found"
}{
"shortMessage": "SAML Connection can't be activated",
"longMessage": "You have to provide the <fields> before you are able to activate this connection.",
"code": "saml_connection_cant_be_activated"
}{
"shortMessage": "Email address domain mismatch",
"longMessage": "The email address domain of the provider's account does not match the domain of the connection.",
"code": "saml_email_address_domain_mismatch",
"meta": {
"expecteddomain": "expecteddomain",
"receiveddomain": "receiveddomain"
}
}{
"shortMessage": "email address domain is used for SAML SSO",
"longMessage": "You can't use this email address, as SAML SSO is enabled for the specific domain.",
"code": "saml_email_address_domain_reserved"
}{
"shortMessage": "Email address mismatch",
"longMessage": "The provided email address differs from the one in the SAML response (IdP email: <email>).",
"code": "saml_email_address_domain_mismatch"
}{
"shortMessage": "Failed to fetch IdP metadata",
"longMessage": "We failed to fetch the IdP metadata. If the error persists, please provide the IdP configuration data explicitly.",
"code": "saml_failed_to_fetch_idp_metadata"
}{
"shortMessage": "Failed to parse IdP metadata",
"longMessage": "We failed to parse the IdP metadata. If the error persists, please provide the IdP configuration data explicitly.",
"code": "saml_failed_to_parse_idp_metadata"
}
SAMLJITProvisioningDisabled signifies that a SAML user could not be signed in
because JIT provisioning is disabled for the connection and no matching user
exists. The blocked email address is surfaced in the meta so it shows up in
the dashboard debug logs.
{
"shortMessage": "JIT provisioning disabled",
"longMessage": "Just-in-time provisioning is disabled for this SAML connection and no matching user exists for the provided email address.",
"code": "saml_jit_provisioning_disabled",
"meta": {
"emailaddress": "emailaddress"
}
}{
"shortMessage": "IdP metadata is missing required fields",
"longMessage": "The IdP metadata is missing the following required fields: <fields>",
"code": "saml_metadata_missing_fields",
"meta": {
"missingfields": "missingfields"
}
}{
"shortMessage": "SAML SSO not enabled",
"longMessage": "SAML SSO is not enabled for this email address.",
"code": "saml_connection_not_found",
"meta": {
"name": "param"
}
}{
"shortMessage": "Invalid SAML response",
"longMessage": "The SAML response is invalid.<optionalReason>",
"code": "saml_response_invalid"
}{
"shortMessage": "RelayState parameter is missing from the SAML Response",
"longMessage": "The RelayState parameter is missing from the SAML Response. Note that RelayState is not required if you are using the IdP-initiated flow. See https://clerk.com/docs/guides/configure/auth-strategies/enterprise-connections/authentication-flows#saml",
"code": "saml_response_relaystate_missing"
}{
"shortMessage": "",
"longMessage": "This account does not have an associated '<attrName>' attribute. Contact the IdP administrator for resolution.",
"code": "saml_user_attribute_missing",
"meta": {
"missingattribute": "attrname"
}
}Scim
SCIMAttributeManagedByDirectory returns a 409 Conflict error when attempting to
update an attribute that is managed by a directory.
{
"shortMessage": "attribute managed by directory sync",
"longMessage": "attribute managed by directory sync",
"code": "attribute_managed_by_scim",
"meta": {
"name": "paramname"
}
}{
"shortMessage": "enterprise connection already in use",
"longMessage": "This enterprise connection is already associated with another directory.",
"code": "scim_directory_enterprise_connection_already_used",
"meta": {
"name": "scim_connection_id"
}
}
SCIMDirectoryOrganizationAlreadyUsed returns an error when attempting to
create a SCIM directory for an organization that already has one. [paramName]
identifies the request parameter through which the organization was supplied.
{
"shortMessage": "organization already has a SCIM directory",
"longMessage": "This organization is already associated with another SCIM directory.",
"code": "scim_directory_organization_already_used",
"meta": {
"name": "paramname"
}
}
SCIMDirectoryProviderNotSelfServable returns an error when a self-serve
(FAPI) directory operation targets a pull-based provider (e.g. Google
Workspace), which can only be managed from the Clerk Dashboard.
{
"shortMessage": "provider not self-servable",
"longMessage": "Google Workspace connections do not support self-serve Directory Sync. Configure Directory Sync from the Clerk Dashboard.",
"code": "scim_directory_provider_not_self_servable"
}{
"shortMessage": "unable to create session",
"longMessage": "Unable to create new session when an impersonation session is present. Please sign out first.",
"code": "session_creation_not_allowed"
}{
"shortMessage": "account deprovisioned",
"longMessage": "Your account is deprovisioned",
"code": "deprovisioned"
}
InvalidActionForSession signifies an error occurred when user tries to perform invalid action on a session
{
"shortMessage": "Invalid action for user session",
"longMessage": "Unable to <action> session <sessionID>",
"code": "invalid_action_for_session"
}{
"shortMessage": "Invalid action for session reverification",
"longMessage": "We were unable to <action> for this session, as it's not ready for <resolution>.",
"code": "invalid_action_for_session_reverification"
}
SessionNotFound signifies an error when no session with given sessionID was found
{
"shortMessage": "Session not found",
"longMessage": "No session was found with id <sessionID>",
"code": "resource_not_found"
}{
"shortMessage": "is missing",
"longMessage": "You need to start a new session verification flow first",
"code": "session_reverification_missing"
}{
"shortMessage": "Reverification required",
"longMessage": "You need to provide additional verification to perform this operation",
"code": "session_reverification_required"
}
UnauthorizedActionForSession signifies an error occurred when the requestor is not authorized to perform the
requested action to the respective session.
{
"shortMessage": "Unauthorized action for session",
"longMessage": "Not authorized to perform requested action on session <sessionID>",
"code": "action_for_session_not_authorized"
}Sign In
AccountLockoutWarning returns an error that warns the user about remaining attempts
before their account gets locked. This should be used when a user has 2, 1, or 0 attempts remaining.
{
"shortMessage": "",
"code": "account_lockout_warning"
}
AccountTransferInvalid signifies an error when no account was found to transfer
{
"shortMessage": "Invalid account transfer",
"longMessage": "There is no account to transfer",
"code": "account_transfer_invalid"
}
AlreadySignedIn signifies an error when given session ID is already signed in
{
"shortMessage": "You're already signed in",
"longMessage": "You're already signed in",
"code": "identifier_already_signed_in",
"meta": "session"
}
IdentificationBelongsToDifferentUser indicates an error when a user
is trying to perform an operation (e.g. sign in prepare) with an
identification that doesn't belong to him.
{
"shortMessage": "belongs to different user",
"longMessage": "The given identification belongs to a different user.",
"code": "resource_forbidden"
}
IdentificationClaimed signifies an error when the requested identification is already claimed by another user
{
"shortMessage": "Identification claimed by another user",
"longMessage": "One or more identifiers on this sign up have since been connected to a different User. Please sign up again.",
"code": "identification_claimed"
}
InvalidClientStateForAction signifies an error when trying to perform an invalid action for the current client state
{
"shortMessage": "Invalid action",
"longMessage": "We were unable to complete <action> for this Client. <resolution>",
"code": "client_state_invalid"
}
InvalidStrategyForUser signifies an error when the supplied verification strategy is not valid for the account
{
"shortMessage": "Invalid verification strategy",
"longMessage": "The verification strategy is not valid for this account",
"code": "strategy_for_user_invalid"
}
MutationOnOlderSignInNotAllowed signifies an error when trying to mutate an older sign in
{
"shortMessage": "Update operations are not allowed on older sign ins",
"longMessage": "Update operations are not allowed on older sign ins",
"code": "resource_forbidden"
}{
"shortMessage": "no second factors",
"longMessage": "No second factors were found for strategy <strategy>.",
"code": "no_second_factors"
}{
"shortMessage": "email link sign in cannot be completed",
"longMessage": "Email link sign in cannot be completed because it originates from a different client",
"code": "sign_in_email_link_not_same_client"
}{
"shortMessage": "identification or user deleted",
"longMessage": "Either the user or the selected identification were deleted. Please start over.",
"code": "sign_in_identification_or_user_deleted"
}{
"shortMessage": "sign in with must use enterprise connection email address",
"longMessage": "Your account is linked to an enterprise connection. You must sign in with an email address.",
"code": "sign_in_must_use_enterprise_connection_identifier"
}{
"shortMessage": "no identification for user",
"longMessage": "The given token doesn't have an associated identification for the user who created it.",
"code": "sign_in_no_identification_for_user"
}
UserNotFound signifies an error when no user is found with userID
{
"shortMessage": "not found",
"longMessage": "No sign in was found with id <signInID>",
"code": "resource_not_found"
}
SignUpIfMissingIdentifierNotSupported signifies that the identifier attribute cannot be used with sign_up_if_missing
{
"shortMessage": "identifier not supported with sign_up_if_missing",
"longMessage": "The <identifier> identifier cannot be used with sign_up_if_missing, because verification is required.",
"code": "sign_up_if_missing_not_allowed"
}
SignUpIfMissingNotAllowed signifies an error when sign_up_if_missing cannot be used
due to instance configuration (restricted mode, captcha, etc.)
{
"shortMessage": "sign_up_if_missing not allowed",
"longMessage": "The sign_up_if_missing option cannot be used: <reason>",
"code": "sign_up_if_missing_not_allowed"
}
SignUpIfMissingStrategyMismatch signifies that the prepare strategy doesn't match the initial identification type
{
"shortMessage": "strategy mismatch with sign_up_if_missing",
"longMessage": "When using sign_up_if_missing, you must use a strategy that matches your initial identification type (<identificationType>), but <strategy> was provided.",
"code": "sign_up_if_missing_strategy_not_supported"
}
SignUpIfMissingStrategyNotSupported signifies that the strategy cannot be used with sign_up_if_missing
{
"shortMessage": "strategy not supported with sign_up_if_missing",
"longMessage": "The <strategy> strategy cannot be used with the sign_up_if_missing option because it cannot be used to sign up a new user.",
"code": "sign_up_if_missing_strategy_not_supported"
}{
"shortMessage": "user not found, transfer to sign up",
"longMessage": "The sign in failed because there is no matching user. Please perform a transfer to sign up.",
"code": "sign_up_if_missing_transfer"
}
SingleModeSessionExists signifies an error when session already exists but we are in single session mode
{
"shortMessage": "Session already exists",
"longMessage": "You're already signed in.",
"code": "session_exists"
}{
"shortMessage": "sign in token has already been used",
"longMessage": "This sign in token has already been used. Each token can only be used once.",
"code": "sign_in_token_already_used_code"
}{
"shortMessage": "not in sign in",
"longMessage": "Sign in tokens can only be used during sign in.",
"code": "sign_in_token_not_in_sign_in_code"
}{
"shortMessage": "sign in token cannot be used",
"longMessage": "This sign in token cannot be used anymore. Please request a new one.",
"code": "sign_in_token_cannot_be_used_code"
}{
"shortMessage": "sign in token has been revoked",
"longMessage": "This sign in token has been revoked and cannot be used anymore.",
"code": "sign_in_token_revoked_code"
}{
"shortMessage": "Error loading CAPTCHA",
"longMessage": "The CAPTCHA failed to load. This may be due to an unsupported browser or a browser extension. Please try a different browser or disabling extensions. If this issue persists, please contact support.",
"code": "captcha_invalid"
}{
"shortMessage": "Authentication unsuccessful due to failed security validations.",
"longMessage": "Authentication unsuccessful due to failed security validations. Please try using a different browser or disabling browser extensions. If issues persist, contact support for assistance.",
"code": "captcha_invalid"
}{
"shortMessage": "Authentication unsuccessful due to failed security validations.",
"longMessage": "Authentication unsuccessful due to failed security validations. Please refresh the page to try again or reach out to support for more assistance.",
"code": "captcha_missing_token"
}{
"shortMessage": "CAPTCHA not enabled",
"longMessage": "You attempted to complete a CAPTCHA, but they are not enabled. If this issue persists, please contact support.",
"code": "captcha_not_enabled"
}{
"shortMessage": "email link sign up cannot be completed",
"longMessage": "Email link sign up cannot be completed because it originates from a different client",
"code": "sign_up_email_link_not_same_client"
}{
"shortMessage": "Sign up forbidden",
"longMessage": "Access to this sign up is forbidden",
"code": "resource_forbidden"
}{
"shortMessage": "Sign-ups restricted",
"longMessage": "New sign-ups are currently restricted.",
"code": "sign_up_mode_restricted"
}{
"shortMessage": "Sign-ups restricted with waitlist",
"longMessage": "Sign-ups are currently unavailable. Join the waitlist, and you will be notified when access becomes available.",
"code": "sign_up_restricted_waitlist"
}
SignUpNotFound returns an API error where no sign up could be found with
the requested ID.
{
"shortMessage": "Sign up not found",
"longMessage": "No sign up was found with id <id>",
"code": "resource_not_found"
}{
"shortMessage": "Outdated verification",
"longMessage": "There is a more recent verification pending for this signup. Try attempting the verification again.",
"code": "sign_up_outdated_verification"
}Sms
DevMonthlySMSLimitExceeded signifies an error when an SMS sending attempt is made while the development limit has already been reached
{
"shortMessage": "Development monthly SMS limit exceeded",
"longMessage": "Operation cannot be completed because the monthly limit for SMS messages in development (%d) has been reached.",
"code": "dev_monthly_sms_limit_exceeded",
"meta": "{\"limit\"}"
}{
"shortMessage": "Sending SMS failed",
"longMessage": "Sending SMS failed. Please contact support or try again later.",
"code": "sms_send_error"
}{
"shortMessage": "ticket has expired",
"longMessage": "This ticket has expired and cannot be used anymore.",
"code": "ticket_expired_code"
}{
"shortMessage": "ticket is invalid",
"longMessage": "This ticket is invalid. Make sure you're using a valid ticket generated by Clerk.",
"code": "ticket_invalid_code"
}{
"shortMessage": "invalid TOTP secret",
"longMessage": "The TOTP secret is invalid, please provide a valid one base32 encoded",
"code": "invalid_totp_secret_code"
}
TOTPAlreadyEnabled signifies an error when a user attempts to enable TOTP, but it's already enabled.
{
"shortMessage": "TOTP already enabled",
"longMessage": "TOTP is already enabled on your account",
"code": "totp_already_enabled"
}{
"shortMessage": "trusted device already enrolled",
"longMessage": "A trusted device is already enrolled for this user and app installation.",
"code": "trusted_device_already_enrolled"
}{
"shortMessage": "app identifier not configured",
"longMessage": "Trusted device app identifier is not configured for this instance",
"code": "trusted_device_app_identifier_not_configured"
}{
"shortMessage": "binding mismatch",
"longMessage": "Trusted device challenge binding mismatch",
"code": "trusted_device_binding_mismatch",
"meta": {
"name": "param"
}
}{
"shortMessage": "challenge expired",
"longMessage": "Trusted device challenge expired",
"code": "trusted_device_challenge_expired"
}{
"shortMessage": "challenge not found",
"longMessage": "Trusted device challenge not found",
"code": "trusted_device_challenge_not_found"
}{
"shortMessage": "trusted device credential quota exceeded",
"longMessage": "You have reached your limit of %d trusted devices per account.",
"code": "trusted_device_credential_quota_exceeded"
}{
"shortMessage": "is invalid",
"longMessage": "Invalid trusted device client data",
"code": "trusted_device_invalid_client_data",
"meta": {
"name": "param"
}
}{
"shortMessage": "is invalid",
"longMessage": "Invalid trusted device public key",
"code": "trusted_device_invalid_public_key",
"meta": {
"name": "param"
}
}{
"shortMessage": "not registered",
"longMessage": "Trusted device is not registered.",
"code": "trusted_device_not_registered",
"meta": {
"name": "param"
}
}{
"shortMessage": "signature verification failed",
"longMessage": "Trusted device signature verification failed",
"code": "trusted_device_signature_verification_failed"
}{
"shortMessage": "Insecure URL",
"longMessage": "Please provide a secure URL (https)",
"code": "insecure_url",
"meta": {
"name": "paramname"
}
}{
"shortMessage": "Invalid URL scheme",
"longMessage": "Please provide a URL with one of the following schemes: <schemes>",
"code": "invalid_url_scheme",
"meta": {
"name": "paramname"
}
}{
"shortMessage": "Account locked",
"longMessage": "Your account is locked. You will be able to try again in <timeRemaining>. For more information, please contact <support>.",
"code": "user_locked"
}{
"shortMessage": "Account locked",
"longMessage": "Your account is locked. For more information, please contact <support>.",
"code": "user_locked"
}{
"shortMessage": "forbidden",
"longMessage": "Resource forbidden",
"code": "resource_forbidden"
}{
"shortMessage": "not found",
"longMessage": "Resource not found",
"code": "resource_not_found"
}Users
DeleteLinkedCommNotAllowed signifies an error when trying to delete a linked communication
TODO Alex: Check if this is the correct place for this error
{
"shortMessage": "Deleting a linked email address is not allowed",
"longMessage": "This email address is linked to one or more Connected Accounts. Remove the Connected Account before deleting this email address.",
"code": "delete_linked_identification_disallowed"
}{
"shortMessage": "no password set",
"longMessage": "This user does not have a password set for their account",
"code": "no_password_set"
}{
"shortMessage": "password required",
"longMessage": "Settings for this instance require a password to be set. Cannot remove the user's password.",
"code": "password_required"
}{
"shortMessage": "password reset required",
"longMessage": "This account requires a password reset before sign-in can continue. Please reset your password or contact support.",
"code": "password_reset_required"
}{
"shortMessage": "imported password too long and needs reset",
"longMessage": "The existing imported password is too long and cannot be used, please reset your password.",
"code": "password_too_long_needs_reset"
}{
"shortMessage": "deprecated feature",
"longMessage": "Password is not a valid parameter and can only be updated via /v1/me/change_password",
"code": "updating_user_password_deprecated"
}
UserBanned signifies an error when a user is banned
{
"shortMessage": "User banned",
"longMessage": "You have been banned. If you think this was by mistake, please contact support.",
"code": "user_banned"
}{
"shortMessage": "create organization not enabled",
"longMessage": "Organization creation is not enabled for this user",
"code": "user_create_organization_not_enabled"
}{
"shortMessage": "User deactivated",
"longMessage": "You have been deactivated. Please contact support.",
"code": "user_deactivated"
}{
"shortMessage": "delete self not enabled",
"longMessage": "Self deletion is not enabled for this user",
"code": "user_delete_self_not_enabled"
}
UserNotFound signifies an error when no user is found with userID
{
"shortMessage": "not found",
"longMessage": "No user was found with id <userID>",
"code": "resource_not_found"
}{
"shortMessage": "user quota exceeded",
"longMessage": "You have reached your limit of %d users. <maxAllowed>",
"code": "user_quota_exceeded"
}{
"shortMessage": "user managed by directory sync",
"longMessage": "This user is managed by a directory and cannot be deleted manually.",
"code": "user_managed_by_scim"
}Verification
VerificationAlreadyVerified signifies an error when verification has already been verified
{
"shortMessage": "already verified",
"longMessage": "This verification has already been verified.",
"code": "verification_already_verified"
}{
"shortMessage": "Too many verification code requests",
"longMessage": "Too many verification code requests. Please wait at least 30 seconds to receive your code before trying again.",
"code": "verification_code_too_many_requests"
}
VerificationExpired signifies an error when verification has expired
{
"shortMessage": "expired",
"longMessage": "This verification has expired. You must create a new one.",
"code": "verification_expired"
}
VerificationFailed signifies an error when verification fails
{
"shortMessage": "failed",
"longMessage": "Too many failed attempts. You have to try again with the same or another method.",
"code": "verification_failed"
}
VerificationInvalidLinkToken means that the provided JWT token from the
link cannot be parsed.
{
"shortMessage": "invalid link token",
"longMessage": "Verification link token is invalid",
"code": "verification_link_token_invalid"
}
VerificationInvalidLinkTokenSource means that the provided JWT token from
the link has an invalid source type.
{
"shortMessage": "invalid link token source",
"longMessage": "Verification link token source is invalid",
"code": "verification_link_token_source_invalid"
}
VerificationInvalidStrategy signifies an error when the given strategy is not valid for current verification
{
"shortMessage": "has invalid strategy",
"longMessage": "The strategy is not valid for the current verification.",
"code": "verification_strategy_invalid"
}
VerificationLinkTokenExpired means that the provided JWT token from the
link has expired.
{
"shortMessage": "expired link token",
"longMessage": "Verification link token has expired",
"code": "verification_link_token_expired"
}
VerificationLinkTokenStale means that the verification link token references
a verification that is no longer current (e.g. the user requested a new
verification after this link was sent).
{
"shortMessage": "stale link token",
"longMessage": "Verification link token is no longer valid. Please request a new one.",
"code": "verification_link_token_stale"
}
VerificationMissing signifies an error when the verification is missing
{
"shortMessage": "is missing",
"longMessage": "This strategy requires verification preparation before attempting to validate it.",
"code": "verification_missing"
}
VerificationNotSent signifies an error when verification email was not sent
{
"shortMessage": "not sent",
"longMessage": "You need to send a verification code before attempting to verify.",
"code": "verification_not_sent"
}
VerificationUnknownStatus signifies an unexpected error when unknown verification status is found
{
"shortMessage": "Unknown verification status",
"longMessage": "Found unknown verification status <status>",
"code": "verification_status_unknown"
}{
"shortMessage": "Waitlist not accepting entries",
"longMessage": "The waitlist is not accepting new entries at this time. Please try again later.",
"code": "waitlist_not_accepting_entries"
}Feedback
Last updated on