Backend API errors
{
"errors": [
{
"message": "cannot revoke",
"long_message": "Actor token cannot be revoked because its status is <status>. Only pending tokens can be revoked.",
"code": "actor_token_cannot_be_revoked_code"
}
]
}{
"errors": [
{
"message": "cannot revoke agent task",
"long_message": "Agent task cannot be revoked because it has status <status>.",
"code": "agent_task_cannot_be_revoked"
}
]
}{
"errors": [
{
"message": "agent task not found",
"long_message": "The requested agent task could not be found.",
"code": "agent_task_not_found"
}
]
}{
"errors": [
{
"message": "user not found",
"long_message": "The user of the agent task no longer exists. Please request a new one.",
"code": "agent_task_subject_not_found"
}
]
}{
"errors": [
{
"message": "Identifier not found",
"long_message": "No identifier was found with id <identifierID>",
"code": "resource_not_found"
}
]
}{
"errors": [
{
"message": "duplicate allowlist identifier",
"long_message": "the identifier <identifier> already exists",
"code": "duplicate_record"
}
]
}{
"errors": [
{
"message": "API Keys not enabled",
"long_message": "API Keys not enabled",
"code": "api_keys_not_enabled"
}
]
}Applications
AccountlessApplicationNotFound signifies an error when no application with the given claim token could be found
{
"errors": [
{
"message": "Application not found",
"long_message": "No application was found with the given claim token.",
"code": "resource_not_found"
}
]
}Auth
AuthorizationMissingScopes signifies that the authorization is missing required scope(s).
Returns a 403 Forbidden error.
{
"errors": [
{
"message": "Missing authorization scopes",
"long_message": "The authorization is missing required scope(s): <missing>.",
"code": "authorization_missing_scopes",
"meta": {
"scopes": [
"<missing>"
]
}
}
]
}{
"errors": [
{
"message": "Could not authenticate request.",
"long_message": "Could not authenticate request.",
"code": "could_not_authenticate_request"
}
]
}
IdentificationExists is returned when the identifier already exists. The code
depends on the identifier type: email_address_exists, phone_number_exists,
username_exists, or external_account_exists.
{
"errors": [
{
"message": "already exists",
"long_message": "This <identifier> already exists.",
"code": "<code>"
}
]
}{
"errors": [
{
"message": "Country code not allowed.",
"long_message": "Phone number sign ups are not allowed for this country code. Please use a different method.",
"code": "not_allowed_access",
"meta": {
"param_name": "phone_number"
}
}
]
}{
"errors": [
{
"message": "Access not allowed.",
"long_message": "<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
{
"errors": [
{
"message": "Invalid authentication",
"long_message": "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
{
"errors": [
{
"message": "Unauthorized request",
"long_message": "You are not authorized to perform this request",
"code": "authorization_invalid"
}
]
}
InvalidAuthorizationHeaderFormat signifies an error when the Authorization header has no proper format.
{
"errors": [
{
"message": "Invalid Authorization header format",
"long_message": "Invalid Authorization header format. Must be 'Bearer <YOUR_API_KEY>'",
"code": "authorization_header_format_invalid"
}
]
}
InvalidClerkSecretKey signifies an error when the supplied secret key is invalid
{
"errors": [
{
"message": "The provided Clerk Secret Key is invalid. Make sure that your Clerk Secret Key is correct.",
"long_message": "The provided Clerk Secret Key is invalid. Make sure that your Clerk Secret Key is correct.",
"code": "clerk_key_invalid"
}
]
}
InvalidRequestForEnvironment signifies an error when the incoming request is invalid for given environment(s)
{
"errors": [
{
"message": "Invalid request for environment",
"long_message": "Request only valid for <envTypes> instances.",
"code": "request_invalid_for_environment"
}
]
}
RateLimitedCountry is returned when Clerk has temporarily disabled SMS to the
phone number's country.
{
"errors": [
{
"message": "Rate limited country code",
"long_message": "SMS to the country <countryName> is temporarily disabled. Please try again later.",
"code": "unsupported_country_code",
"meta": {
"alpha2": "<alpha2>",
"country_code": "<countryCode>"
}
}
]
}
RequestInvalidForInstance signifies an error when the incoming request is invalid for the instance's settings
{
"errors": [
{
"message": "Invalid request for instance",
"long_message": "This request is not valid for your instance. Modify your instance settings to use this request.",
"code": "request_invalid_for_instance"
}
]
}{
"errors": [
{
"message": "This email address is already in use.",
"long_message": "This email address is already in use. Creating multiple accounts with the same email address is not allowed.",
"code": "not_allowed_access"
}
]
}{
"errors": [
{
"message": "Unsupported country code",
"long_message": "Phone numbers from this country (<countryName>) are currently not supported. For more information, please contact <support>.",
"code": "unsupported_country_code",
"meta": {
"alpha2": "<alpha2>",
"country_code": "<countryCode>"
}
}
]
}{
"errors": [
{
"message": "Identifier not found",
"long_message": "No identifier was found with id <identifierID>",
"code": "resource_not_found"
}
]
}{
"errors": [
{
"message": "duplicate blocklist identifier",
"long_message": "the identifier <identifier> already exists",
"code": "duplicate_record"
}
]
}{
"errors": [
{
"message": "Client not found",
"long_message": "No client was found with id <clientID>",
"code": "resource_not_found"
}
]
}
ClientNotFoundInRequest signifies an error when no client is found in an incoming request
{
"errors": [
{
"message": "No client found",
"long_message": "This request is expecting a client and did not find one",
"code": "client_not_found"
}
]
}{
"errors": [
{
"message": "Annual only plans are not enabled",
"long_message": "Annual only plans are not enabled, please enable the update in Clerk dashboard.",
"code": "billing_annual_only_plans_not_enabled"
}
]
}{
"errors": [
{
"message": "access denied",
"long_message": "The billing feature for organizations is not enabled for this instance. You can enable it at https://dashboard.clerk.com.",
"code": "billing_not_enabled"
}
]
}{
"errors": [
{
"message": "access denied",
"long_message": "The billing feature for users is not enabled for this instance. You can enable it at https://dashboard.clerk.com.",
"code": "billing_not_enabled"
}
]
}{
"errors": [
{
"message": "Another checkout is already in progress",
"long_message": "Another checkout is already in progress",
"code": "checkout_already_in_progress"
}
]
}{
"errors": [
{
"message": "Insufficient seats",
"long_message": "You have reached the seat limit for your current plan.",
"code": "insufficient_seats",
"meta": {
"seats_quantity_to_add": 0,
"seats_quantity": 0
}
}
]
}{
"errors": [
{
"message": "Subscription item already canceled",
"long_message": "You can't cancel a subscription item that is already canceled",
"code": "commerce_subscription_item_already_canceled"
}
]
}{
"errors": [
{
"message": "Subscription item cannot be canceled",
"long_message": "Subscription item cannot be canceled because <reason>",
"code": "commerce_subscription_item_cannot_be_canceled"
}
]
}{
"errors": [
{
"message": "Subscription item cannot be ended",
"long_message": "Subscription item cannot be ended because <reason>",
"code": "commerce_subscription_item_cannot_be_ended"
}
]
}{
"errors": [
{
"message": "Invalid currency",
"long_message": "Currency is not supported",
"code": "currency_invalid"
}
]
}{
"errors": [
{
"message": "Default plan price creation forbidden",
"long_message": "Custom prices cannot be created for default plans. Only custom paid plans support additional pricing",
"code": "default_plan_price_creation_forbidden"
}
]
}{
"errors": [
{
"message": "Insufficient credit balance",
"long_message": "The decrease amount exceeds the current credit balance",
"code": "insufficient_credit_balance",
"meta": {
"param_name": "amount"
}
}
]
}{
"errors": [
{
"message": "Invalid credit action",
"long_message": "Credit action must be either 'increase' or 'decrease'",
"code": "invalid_credit_action"
}
]
}{
"errors": [
{
"message": "Invalid credit amount",
"long_message": "Credit amount must be greater than zero",
"code": "invalid_credit_amount"
}
]
}{
"errors": [
{
"message": "Missing plan ID",
"long_message": "Plan ID is required to perform this operation",
"code": "missing_plan_id"
}
]
}{
"errors": [
{
"message": "Organization member limit exceeded",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "Out of date price",
"long_message": "There was a mismatch in the price transition. The price may have been changed by another request.",
"code": "out_of_date_price"
}
]
}{
"errors": [
{
"message": "Payee not active",
"long_message": "Payee is not active",
"code": "payee_not_active"
}
]
}{
"errors": [
{
"message": "Payee not found",
"long_message": "Payee not found",
"code": "payee_not_found"
}
]
}{
"errors": [
{
"message": "Payee status is invalid",
"long_message": "Payee status is invalid",
"code": "payee_status_invalid"
}
]
}{
"errors": [
{
"message": "Payer not found",
"long_message": "Payer not found",
"code": "payer_not_found"
}
]
}{
"errors": [
{
"message": "Requires confirmation",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "Your card was declined",
"long_message": "The card was declined.",
"code": "payment_attempt_failed_card_declined"
}
]
}{
"errors": [
{
"message": "Card expired",
"long_message": "The card has expired.",
"code": "payment_attempt_failed_card_expired"
}
]
}{
"errors": [
{
"message": "Insufficient funds",
"long_message": "The card has insufficient funds.",
"code": "payment_attempt_failed_card_insufficient_funds"
}
]
}{
"errors": [
{
"message": "Payment method required",
"long_message": "A payment method is required to upgrade from a free plan. The subscription payer must add a payment method before this transition can be completed.",
"code": "payment_method_required_for_transition"
}
]
}{
"errors": [
{
"message": "Processing error",
"long_message": "There was a processing error with the payment method.",
"code": "payment_attempt_failed_processing_error"
}
]
}{
"errors": [
{
"message": "Paid plan month or annual fee invalid",
"long_message": "Paid plan month or annual fee invalid",
"code": "plan_amount_invalid"
}
]
}{
"errors": [
{
"message": "Paid plan monthly base fee exceeds upper limit",
"long_message": "Paid plan monthly base fee must be less than $999,999.99",
"code": "plan_amount_exceeds_upper_limit"
}
]
}{
"errors": [
{
"message": "Plan does not support empty organizations",
"long_message": "This plan cannot be applied to an organization without members.",
"code": "plan_does_not_support_empty_orgs"
}
]
}{
"errors": [
{
"message": "Free trials disabled",
"long_message": "Free trials are disabled for this plan",
"code": "plan_free_trials_disabled"
}
]
}{
"errors": [
{
"message": "Plan not found",
"long_message": "Plan not found",
"code": "plan_not_found"
}
]
}{
"errors": [
{
"message": "Plan seat limit exceeded",
"long_message": "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": {
"plan_seat_limit": 0,
"current_members": 0
}
}
]
}{
"errors": [
{
"message": "Price transition not allowed",
"long_message": "Price transition not allowed because <reason>",
"code": "price_transition_not_allowed"
}
]
}{
"errors": [
{
"message": "Seat-based billing exceeds plan's organization member limit",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "Subscription already ended",
"long_message": "Subscription is already ended",
"code": "subscription_already_ended"
}
]
}{
"errors": [
{
"message": "Subscription item is no longer active",
"long_message": "The subscription item is no longer the payer's active subscription item. It may have been changed by another request.",
"code": "subscription_item_no_longer_active"
}
]
}{
"errors": [
{
"message": "Subscription item not found",
"long_message": "Subscription item not found",
"code": "subscription_item_not_found"
}
]
}{
"errors": [
{
"message": "Subscription item is not in free trial",
"long_message": "Subscription item is not in free trial",
"code": "subscription_item_not_in_free_trial"
}
]
}{
"errors": [
{
"message": "Subscription not found",
"long_message": "Subscription not found",
"code": "subscription_not_found"
}
]
}{
"errors": [
{
"message": "Supported billing period mismatch",
"long_message": "<field> cannot be set when supported_billing_periods is \"<period>\"",
"code": "supported_billing_period_mismatch",
"meta": {
"param_name": "<field>"
}
}
]
}{
"errors": [
{
"message": "Invalid unit price amount per block",
"long_message": "Unit price '<unitName>' tier <tierNumber> has invalid amount_per_block '<amountPerBlock>'. Amount per block must be non-negative (>= 0)",
"code": "unit_price_amount_per_block_invalid"
}
]
}{
"errors": [
{
"message": "Invalid unit price block size",
"long_message": "Unit price block size '<blockSize>' is not supported. Supported block size: <validBlockSize>",
"code": "unit_price_block_size_invalid"
}
]
}{
"errors": [
{
"message": "Invalid unit price currency",
"long_message": "Unit price currency '<currency>' is not supported. Only '<validCurrency>' is currently supported for unit prices",
"code": "unit_price_currency_invalid"
}
]
}{
"errors": [
{
"message": "Invalid tier range",
"long_message": "Unit price '<unitName>' tier <tierNumber> has ends_after_block (<endsAfterBlock>) less than starts_at_block (<startsAtBlock>). The end must be greater than or equal to the start",
"code": "unit_price_ends_after_block_invalid"
}
]
}{
"errors": [
{
"message": "Free tier cannot follow a paid tier",
"long_message": "Unit price '<unitName>' tier <tierNumber> is free but a preceding tier is paid. Once a tier is paid, all subsequent tiers must also be paid",
"code": "unit_price_free_tier_after_paid_tier"
}
]
}{
"errors": [
{
"message": "Invalid unit price name",
"long_message": "Unit price name '<name>' is not supported. Supported names: <validName>",
"code": "unit_price_name_invalid"
}
]
}{
"errors": [
{
"message": "Unit prices not allowed for user plans",
"long_message": "unit_prices can only be provided for organization plans, not user plans",
"code": "unit_prices_not_allowed_for_user_plans"
}
]
}{
"errors": [
{
"message": "Invalid unit price starts at block",
"long_message": "Unit price starts at block '<startsAtBlock>' is not supported. Supported starts at block: <validStartsAtBlock>",
"code": "unit_price_starts_at_block_invalid"
}
]
}{
"errors": [
{
"message": "Gap or overlap in tier ranges",
"long_message": "Unit price '<unitName>' tier <tierNumber> should start at block <expectedStart> but starts at <actualStart>. Tiers must be continuous with no gaps or overlaps",
"code": "unit_price_tier_gap_or_overlap_detected"
}
]
}{
"errors": [
{
"message": "Tiers missing",
"long_message": "Unit price '<unitName>' must have at least one tier defined",
"code": "unit_price_tiers_missing"
}
]
}{
"errors": [
{
"message": "Unlimited tier must be last",
"long_message": "Unit price '<unitName>' tier <tierNumber> has unlimited range (null ends_after_block) but is not the last tier. Only the last tier can be unlimited",
"code": "unit_price_unlimited_tier_must_be_last"
}
]
}{
"errors": [
{
"message": "The provided cookie is invalid.",
"long_message": "The provided cookie is invalid.",
"code": "cookie_invalid"
}
]
}
InvalidRotatingToken signifies an error when rotating token does not match the client's rotating token
{
"errors": [
{
"message": "The provided cookie is invalid.",
"long_message": "The client's rotating key does not match the given one <token>",
"code": "cookie_invalid"
}
]
}
MissingClaims signifies an error when token is missing claim
{
"errors": [
{
"message": "The provided cookie is invalid.",
"long_message": "The token is missing the following claims: <claims>",
"code": "cookie_invalid"
}
]
}{
"errors": [
{
"message": "endpoint is deprecated and pending removal",
"long_message": "<message>",
"code": "operation_deprecated"
}
]
}{
"errors": [
{
"message": "Discount already applied",
"long_message": "This subscription item already has an active discount applied",
"code": "discount_already_applied"
}
]
}{
"errors": [
{
"message": "Discount inactive",
"long_message": "This discount is not currently active",
"code": "discount_inactive"
}
]
}{
"errors": [
{
"message": "Discount not applicable",
"long_message": "This discount cannot be applied to this subscription item",
"code": "discount_not_applicable_to_subscription_item"
}
]
}{
"errors": [
{
"message": "Discount not found",
"long_message": "The discount was not found",
"code": "discount_not_found"
}
]
}{
"errors": [
{
"message": "Domain is managed by an integration",
"long_message": "The domains of this application are managed by <integrationName>. Update them from the <integrationName> integration settings instead.",
"code": "domain_managed_by_integration",
"meta": {
"integration": "<integrationName>"
}
}
]
}
DomainUpdateForbidden signifies an error when trying to update an non production instance domain
{
"errors": [
{
"message": "Domain update was forbidden",
"long_message": "Domain can be only updated for production instances",
"code": "domain_update_forbidden"
}
]
}
FeatureRequiresCustomDomain signifies an error when a feature is blocked
because the instance only has a provider domain (e.g. vercel.app).
{
"errors": [
{
"message": "custom domain required",
"long_message": "<feature> requires a custom domain. Add a custom domain to unlock this feature.",
"code": "feature_requires_custom_domain"
}
]
}{
"errors": [
{
"message": "<msg>",
"long_message": "Clerk Frontend API cannot be accessed through the proxy URL. Make sure your proxy is configured correctly.",
"code": "invalid_proxy_configuration",
"meta": {
"param_name": "proxy_url"
}
}
]
}{
"errors": [
{
"message": "operation not allowed",
"long_message": "This operation is not allowed on a primary domain. Try again with a satellite domain of the instance.",
"code": "operation_not_allowed_on_primary_domain"
}
]
}
PrimaryDomainAlreadyExists signifies an error when a new domain is added as
primary when there is already once in the instance.
Currently, we only support a single primary domain per instance.
{
"errors": [
{
"message": "primary domain already exists",
"long_message": "Currently, only a single primary domain is supported and the current instance already has one. All new domains need to be set a satellites.",
"code": "primary_domain_already_exists",
"meta": {
"param_name": "is_satellite"
}
}
]
}
ProviderDomainOperationNotAllowedForAPI reports a restricted provider-domain operation outside Platform API.
{
"errors": [
{
"message": "operation not allowed",
"long_message": "*<provider> domains are not supported for production instances. Please purchase a domain then try again.",
"code": "provider_domain_operation_not_allowed"
}
]
}
ProxyURLRequiredForProviderDomain signifies an error when a provider domain
(e.g., replit.app, vercel.app) is created without a proxy URL.
{
"errors": [
{
"message": "proxy URL required",
"long_message": "Provider domain <domainName> requires a proxy URL. Provider domains must be configured with a proxy.",
"code": "proxy_url_required_for_provider_domain",
"meta": {
"param_name": "<paramName>"
}
}
]
}
TransactionalEmailRequiresVerifiedProductionDomain is returned when the
internal transactional-email surface is enabled on an instance whose active
sending domain is not a verified, customer-owned production domain.
{
"errors": [
{
"message": "verified production domain required",
"long_message": "Transactional email requires an active, verified production domain that is not a shared provider domain.",
"code": "transactional_email_requires_verified_production_domain"
}
]
}
DevMonthlyEmailLimitExceeded signifies an error when an email sending attempt is made while the development limit has already been reached
{
"errors": [
{
"message": "Development monthly email limit exceeded",
"long_message": "The monthly limit for email messages in development (<limit>) has been reached. Please use test emails (https://go.clerk.com/test-emails) instead",
"code": "dev_monthly_email_limit_exceeded",
"meta": {
"dev_monthly_email_limit": 0
}
}
]
}
TransactionalEmailIdempotencyConflict is returned when an idempotency key
cannot represent the requested send without creating a second logical email.
{
"errors": [
{
"message": "idempotency key conflict",
"long_message": "<message>",
"code": "transactional_email_idempotency_conflict"
}
]
}
TransactionalEmailSenderDomainMismatch is returned when a caller-supplied
sender or reply-to address does not use the instance's bound sending domain.
{
"errors": [
{
"message": "sender domain mismatch",
"long_message": "<parameter> must use the verified production sending domain <domain>.",
"code": "transactional_email_sender_domain_mismatch",
"meta": {
"param_name": "<parameter>"
}
}
]
}{
"errors": [
{
"message": "Email template customization is locked",
"long_message": "Email template customization is locked. Revert to the default template or contact support to regain customization access.",
"code": "email_template_customization_locked"
}
]
}{
"errors": [
{
"message": "Email template customization rate limit exceeded",
"long_message": "The email template customization rate limit was exceeded. Please try again later or contact support if you continue to experience issues.",
"code": "email_template_customization_rate_limited"
}
]
}{
"errors": [
{
"message": "Email template update blocked",
"long_message": "This email template update was detected as suspicious and has been blocked. If you believe this was a mistake, please contact support.",
"code": "email_template_suspicious_blocked",
"meta": {
"remaining_suspicious_attempts_before_lock": 0
}
}
]
}{
"errors": [
{
"message": "No Enterprise Connection for this sign-up",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "user is not served by an enterprise connection",
"long_message": "The user does not have a verified email address on a domain served by an enterprise connection, so they cannot be added to the SSO bypass allowlist.",
"code": "sso_bypass_domain_not_served"
}
]
}{
"errors": [
{
"message": "not enabled",
"long_message": "This feature is not enabled on this instance",
"code": "feature_not_enabled"
}
]
}{
"errors": [
{
"message": "not enabled",
"long_message": "This feature is not enabled on this instance",
"code": "feature_not_enabled",
"meta": {
"param_name": "<paramName>"
}
}
]
}{
"errors": [
{
"message": "Device verification page is not reachable",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "Email address attribute must be enabled",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "not an OIDC provider",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "not a Progressive Sign Up instance",
"long_message": "<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"
}
]
}{
"errors": [
{
"message": "not implemented",
"long_message": "Feature `<feature>` is not available yet",
"code": "feature_not_implemented"
}
]
}{
"errors": [
{
"message": "The <parameter> already exists. Please try another.",
"long_message": "The <parameter> already exists. Please try another.",
"code": "form_already_exists",
"meta": {
"param_name": "<param>"
}
}
]
}
FormAtLeastOneOptionalParameterMissing signifies an error when at least one optional parameter must be provided
{
"errors": [
{
"message": "at least one parameter must be provided",
"long_message": "at least one of `<parameters>` must be provided",
"code": "form_param_missing",
"meta": {
"param_names": [
"<paramNames>"
]
}
}
]
}{
"errors": [
{
"message": "Date values must not be in the future.",
"long_message": "Date values must not be in the future.",
"code": "form_disallow_future_date",
"meta": {
"param_name": "<param>"
}
}
]
}
FormDuplicateParameter signifies an error when a duplicate parameter is found in a form
{
"errors": [
{
"message": "is duplicate",
"long_message": "<param> included multiple times. There should only be one.",
"code": "form_param_duplicate",
"meta": {
"param_name": "<param>"
}
}
]
}
FormDuplicateParameterValue signifies an error when a value has been provided multiple times
{
"errors": [
{
"message": "duplicate values",
"long_message": "<value> contains duplicate values",
"code": "form_param_duplicate",
"meta": {
"param_name": "<param>"
}
}
]
}
FormIdentifierExists signifies an error when given identifier already exists
{
"errors": [
{
"message": "That <parameter> is taken. Please try another.",
"long_message": "That <parameter> is taken. Please try another.",
"code": "form_identifier_exists",
"meta": {
"param_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.
{
"errors": [
{
"message": "This <parameter> is already associated with an existing account. To use this <parameter> with this account, please remove it from your existing account first.",
"long_message": "This <parameter> is already associated with an existing account. To use this <parameter> with this account, please remove it from your existing account first.",
"code": "form_identifier_exists",
"meta": {
"param_name": "<param>"
}
}
]
}
FormIdentifierNotFound signifies an error when a required identifier is not found
{
"errors": [
{
"message": "Couldn't find your account.",
"long_message": "Couldn't find your account.",
"code": "form_identifier_not_found",
"meta": {
"param_name": "<param>"
}
}
]
}
FormIncorrectCode signifies an error when the given code is incorrect
{
"errors": [
{
"message": "is incorrect",
"long_message": "Incorrect code",
"code": "form_code_incorrect",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "Date values must be given in Unix millisecond timestamp format.",
"long_message": "Date values must be given in Unix millisecond timestamp format.",
"code": "form_param_invalid_date",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "is invalid",
"long_message": "<parameter> must be a valid email address.",
"code": "form_param_format_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "is invalid",
"long_message": "<param> must be a valid email address local part.",
"code": "form_param_format_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidEncodingParameterValue signifies an error when the given parameter has an invalid encoding
{
"errors": [
{
"message": "invalid character encoding",
"long_message": "<param> contains invalid UTF-8 characters",
"code": "form_param_value_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "is invalid",
"long_message": "<param> must be either a valid email address, a valid phone number according to E.164 international standard or a valid web3 wallet.",
"code": "form_param_format_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidOrigin signifies an error when the given origin is http/https
{
"errors": [
{
"message": "is invalid",
"long_message": "<param> must be a valid origin such as my-app://localhost, chrome-extension://mnhbilbfebpbokpjjamapdecdgieldho, or capacitor://localhost:3000",
"code": "form_invalid_origin",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidParameterFormat signifies an error when the given parameter has an invalid format
{
"errors": [
{
"message": "<parameter> is invalid.<details>",
"long_message": "<parameter> is invalid.<details>",
"code": "form_param_format_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidParameterFormatBCP47 signifies an error when the given parameter does not match the BCP-47 format
{
"errors": [
{
"message": "is invalid",
"long_message": "<parameter> must be a valid BCP-47 language tag.",
"code": "form_param_format_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "is invalid",
"long_message": "<param> is invalid. Only one of the following parameter values is allowed: <allowedValues>",
"code": "form_param_value_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidParameterValue signifies an error when the given parameter has an invalid value
{
"errors": [
{
"message": "is invalid",
"long_message": "<value> does not match one of the allowed values for parameter <param>",
"code": "form_param_value_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "is invalid",
"long_message": "<param> is invalid. Must be not empty",
"code": "form_param_value_invalid",
"meta": {
"param_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
{
"errors": [
{
"message": "is invalid",
"long_message": "<value> does not match the allowed values for parameter <param>. Allowed values: <allowedValues>",
"code": "form_param_value_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidPasswordLengthTooLong signifies an error when the password is invalid because of its length
{
"errors": [
{
"message": "Passwords must be less than <maxLen> characters.",
"long_message": "Passwords must be less than <maxLen> characters.",
"code": "form_password_length_too_long",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidPasswordLengthTooShort signifies an error when the password is invalid because of its length
{
"errors": [
{
"message": "Passwords must be <minLen> characters or more.",
"long_message": "Passwords must be <minLen> characters or more.",
"code": "form_password_length_too_short",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "Passwords must contain at least one lowercase character.",
"long_message": "Passwords must contain at least one lowercase character.",
"code": "form_password_no_lowercase",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "Passwords must contain at least one number.",
"long_message": "Passwords must contain at least one number.",
"code": "form_password_no_number",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "Passwords must contain at least one of the following special characters: <allowedSpecialChars>.",
"long_message": "Passwords must contain at least one of the following special characters: <allowedSpecialChars>.",
"code": "form_password_no_special_char",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "Given password is not strong enough.",
"long_message": "Given password is not strong enough.",
"code": "form_password_not_strong_enough",
"meta": {
"param_name": "<param>",
"zxcvbn": {
"suggestions": [
"<suggestions>"
]
}
}
}
]
}{
"errors": [
{
"message": "Passwords must contain at least one uppercase character.",
"long_message": "Passwords must contain at least one uppercase character.",
"code": "form_password_no_uppercase",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidPasswordSizeInBytesExceeded is returned when the password exceeds
the maximum size in bytes. A password with multi-byte characters can exceed it
while still under the maximum character length.
{
"errors": [
{
"message": "Your password is too long. Please use a shorter one.",
"long_message": "Your password is too long. Please use a shorter one.",
"code": "form_password_size_in_bytes_exceeded",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "is invalid",
"long_message": "<parameter> must be a valid phone number according to E.164 international standard.",
"code": "form_param_format_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "invalid format",
"long_message": "<param> must contain a datetime specified in RFC3339 format (e.g. `2022-10-20T10:00:27.645Z`).",
"code": "form_param_invalid_time",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidTypeParameter signifies an error when a form parameter has the wrong type
{
"errors": [
{
"message": "is invalid",
"long_message": "`<param>` must be a `<paramType>`.",
"code": "form_param_type_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidUsernameCharacter signifies an error when the given username does not match username regex
{
"errors": [
{
"message": "<parameter> can only contain <allowedCharsString>.",
"long_message": "<parameter> can only contain <allowedCharsString>.",
"code": "form_username_invalid_character",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidUsernameLength signifies an error when the given username does not have required length
{
"errors": [
{
"message": "<parameter> must be between <mininum> and <maximum> characters long.",
"long_message": "<parameter> must be between <mininum> and <maximum> characters long.",
"code": "form_username_invalid_length",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidUsernameNeedsNonNumberCharCode signifies an error when the given username does not match username regex
{
"errors": [
{
"message": "<parameter> must contain one non-number character.",
"long_message": "<parameter> must contain one non-number character.",
"code": "form_username_needs_non_number_char",
"meta": {
"param_name": "<param>"
}
}
]
}
FormInvalidWeb3WalletAddress signifies an error when the given web3 wallet address is invalid
{
"errors": [
{
"message": "is invalid",
"long_message": "<parameter> must be a valid web3 wallet address.",
"code": "form_param_format_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormMetadataInvalidType signifies an error when the given metadata is not a valid key-value object
{
"errors": [
{
"message": "<key> must be a valid key-value object. To reset the <metadataType>, use an empty object (\"{}\").",
"long_message": "<key> must be a valid key-value object. To reset the <metadataType>, use an empty object (\"{}\").",
"code": "form_param_value_invalid",
"meta": {
"param_name": "<param>"
}
}
]
}
FormMissingConditionalParameter signifies an error when required parameter based on conditions is missing
{
"errors": [
{
"message": "is missing",
"long_message": "`<param>` is required when `<leftCondition>` is `<rightCondition>`.",
"code": "form_conditional_param_missing",
"meta": {
"param_name": "<param>"
}
}
]
}
FormMissingConditionalParameterOnExistence signifies an error when parameter is required because of the existence of another
{
"errors": [
{
"message": "is missing",
"long_message": "`<missingParam>` is required when `<conditionalParam>` is present.",
"code": "form_conditional_param_missing",
"meta": {
"param_name": "<missingParam>"
}
}
]
}
FormMissingParameter signifies an error when an expected form parameter is missing
{
"errors": [
{
"message": "is missing",
"long_message": "<param> must be included.",
"code": "form_param_missing",
"meta": {
"param_name": "<param>"
}
}
]
}
FormMissingResource signifies an error when the form parameter is referring to a missing resource
{
"errors": [
{
"message": "is missing",
"long_message": "The resource associated with the supplied <param> was not found.",
"code": "form_resource_not_found",
"meta": {
"param_name": "<param>"
}
}
]
}
FormNilParameter signifies an error when a nil parameter is found in a form
{
"errors": [
{
"message": "Enter <parameter>.",
"long_message": "Enter <parameter>.",
"code": "form_param_nil",
"meta": {
"param_name": "<param>"
}
}
]
}
FormNotAllowedToDisableDefaultSecondFactor signifies an error when trying to disable the default flag from a second-factor
{
"errors": [
{
"message": "The default second factor method can only be changed by assigning another method as the default.",
"long_message": "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": {
"param_name": "<param>"
}
}
]
}
FormParameterArrayLengthMismatch signifies an error when a parallel array
parameter does not have the same number of items as the array it qualifies.
{
"errors": [
{
"message": "length mismatch",
"long_message": "<parameter> must contain exactly one item for each item in <otherParam>.",
"code": "form_param_array_length_mismatch",
"meta": {
"param_name": "<param>"
}
}
]
}
FormParameterArraySizeExceeded signifies an error when the given array exceeds the maximum allowed size
{
"errors": [
{
"message": "exceeds maximum size",
"long_message": "<parameter> should not exceed <maximum> items.",
"code": "form_param_array_size_exceeded",
"meta": {
"param_name": "<param>"
}
}
]
}
FormParameterDeprecated is returned when a request includes a parameter that the
endpoint no longer accepts. The long message can name the replacement, such as a
different endpoint.
{
"errors": [
{
"message": "is deprecated",
"long_message": "<param> is deprecated and is no longer a valid parameter for this request.",
"code": "form_param_deprecated",
"meta": {
"param_name": "<param>"
}
}
]
}
FormParameterMaxLengthExceeded signifies an error when the given param value exceeds the maximum allowed length
{
"errors": [
{
"message": "exceeds maximum length",
"long_message": "<parameter> should not exceed <maximum> characters.",
"code": "form_param_max_length_exceeded",
"meta": {
"param_name": "<param>"
}
}
]
}
FormParameterMinLengthExceeded signifies an error when the given param value is less than the minimum allowed length
{
"errors": [
{
"message": "does not reach minimum length",
"long_message": "<parameter> must be at least <minimum> characters long.",
"code": "form_param_min_length_exceeded",
"meta": {
"param_name": "<param>"
}
}
]
}
FormParameterNotAllowedConditionally signifies an error when parameter is not allowed based on condition
{
"errors": [
{
"message": "is not allowed",
"long_message": "`<param>` isn't allowed when `<leftCondition>` is <rightCondition>.",
"code": "form_conditional_param_disallowed",
"meta": {
"param_name": "<param>"
}
}
]
}
FormParameterNotAllowedIfAnotherParameterIsPresent signifies an error when a parameter is present but
is not allowed because another parameter is also present
{
"errors": [
{
"message": "is not allowed",
"long_message": "`<notAllowedParam>` isn't allowed when `<existingParam>` is present.",
"code": "form_conditional_param_disallowed",
"meta": {
"param_name": "<notAllowedParam>"
}
}
]
}
FormParameterSizeTooLarge signifies an error when a parameter exceeds the max allowed size
{
"errors": [
{
"message": "The given <param> exceeds the maximum allowed size of <maxByteSize> bytes (<maxSizeInKb> KB).",
"long_message": "The given <param> exceeds the maximum allowed size of <maxByteSize> bytes (<maxSizeInKb> KB).",
"code": "form_param_exceeds_allowed_size",
"meta": {
"param_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 can be sent together as long as they agree.
{
"errors": [
{
"message": "conflicting values",
"long_message": "`<param>` and `<otherParam>` refer to the same value, so they must match when both are sent.",
"code": "form_param_value_conflict",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "Value too large",
"long_message": "The value of <param> can't be greater than <maximum>",
"code": "form_param_value_too_large",
"meta": {
"param_name": "<param>"
}
}
]
}
FormPasswordDigestInvalid signifies an error when the provided password_digest is not valid for the provided password_hasher
{
"errors": [
{
"message": "The provided <param> is not a valid <hasher> password hash.",
"long_message": "The provided <param> is not a valid <hasher> password hash.",
"code": "form_password_digest_invalid_code",
"meta": {
"param_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).
{
"errors": [
{
"message": "Password cannot match your email address, phone number or username. For account safety, please use a different password.",
"long_message": "Password cannot match your email address, phone number or username. For account safety, please use a different password.",
"code": "form_password_matches_identifier",
"meta": {
"param_name": "<param>"
}
}
]
}
FormPasswordValidationFailed signifies a generic error when the password validation failed
{
"errors": [
{
"message": "Incorrect password. Please try again.",
"long_message": "Incorrect password. Please try again.",
"code": "form_password_validation_failed",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "is invalid",
"long_message": "PKCE is required for OAuth clients without a secret",
"code": "form_public_client_requires_pkce",
"meta": {
"param_name": "<param>"
}
}
]
}
FormPwnedPassword signifies an error when the chosen password has been found in the pwned list
{
"errors": [
{
"message": "Password has been found in an online data breach. For account safety, please <action>.",
"long_message": "Password has been found in an online data breach. For account safety, please <action>.",
"code": "form_password_pwned",
"meta": {
"param_name": "<param>"
}
}
]
}
FormUnknownParameter signifies an error when an unexpected parameter is found in a form
{
"errors": [
{
"message": "is unknown",
"long_message": "<param> is not a valid parameter for this request.",
"code": "form_param_unknown",
"meta": {
"param_name": "<param>"
}
}
]
}
FormUnknownParameterDueToDisabledFeature signifies an error when an unexpected parameter is found in a form due to a disabled feature
{
"errors": [
{
"message": "is unknown",
"long_message": "<param> is not a valid parameter for this request.<possibleResolution>",
"code": "form_param_unknown",
"meta": {
"param_name": "<param>"
}
}
]
}
FormUnverifiedIdentification signifies an error when the identification included in the form is unverified
{
"errors": [
{
"message": "is unverified",
"long_message": "This identification needs to be verified before you can perform this action.",
"code": "form_verification_needed",
"meta": {
"param_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.
{
"errors": [
{
"message": "<parameter> cannot be a phone number.",
"long_message": "<parameter> cannot be a phone number. Please choose a different username.",
"code": "form_username_cannot_be_phone_number",
"meta": {
"param_name": "<param>"
}
}
]
}
FormValidationFailed is returned when one or more request parameters fail validation.
{
"errors": [
{
"message": "is invalid",
"long_message": "<sanitizedField> is invalid",
"code": "form_param_value_invalid",
"meta": {
"param_name": "<sanitizedField>"
}
}
]
}{
"errors": [
{
"message": "Action blocked",
"long_message": "This action was detected as suspicious and has been blocked. If you believe this was a mistake, please contact support.",
"code": "action_blocked"
}
]
}{
"errors": [
{
"message": "Protect check required",
"long_message": "A Protect check is required before this action can continue.",
"code": "requires_protect_check",
"meta": {
"protect_check": "<protectCheck>"
}
}
]
}Home URL
HomeURLTaken signifies an error when the root domain of the provided home_url already in use by another application
{
"errors": [
{
"message": "Domain already in use",
"long_message": "The <homeURL> root domain is already in use by another application.",
"code": "home_url_taken",
"meta": {
"param_name": "<paramName>"
}
}
]
}
HomeURLTakenByProvider signifies an error when the root domain of the
provided home_url is already used by a provider-managed app.
{
"errors": [
{
"message": "Domain already in use by a <providerName> app",
"long_message": "The <homeURL> root domain is already in use by a <providerName> app. Delete the <providerName> app or contact <providerName> support to remove the domain before using it in Clerk.",
"code": "home_url_taken",
"meta": {
"param_name": "<paramName>"
}
}
]
}
KnownHostingDomain signifies an error when the domain extracted from the provided home_url belongs to a
known hosting service and cannot be used to deploy production apps
{
"errors": [
{
"message": "Known hosting domain",
"long_message": "The <domain> domain cannot be used to deploy production apps.",
"code": "known_hosting_domain",
"meta": {
"param_name": "<paramName>"
}
}
]
}
ReservedDomain signifies an error when the domain extracted from the provided home_url is reserved by Clerk
{
"errors": [
{
"message": "Domain reserved by Clerk",
"long_message": "The <domain> domain is reserved by Clerk.",
"code": "reserved_domain",
"meta": {
"param_name": "<paramName>"
}
}
]
}
ReservedSubdomain signifies an error when the subdomain extracted from the provided home_url is reserved by Clerk
{
"errors": [
{
"message": "Reserved subdomain",
"long_message": "The <subdomain> subdomain is reserved by Clerk.",
"code": "reserved_subdomain",
"meta": {
"param_name": "<paramName>"
}
}
]
}{
"errors": [
{
"message": "Create failed",
"long_message": "Unverified identifications cannot be a second factor",
"code": "identification_create_second_factor_unverified"
}
]
}
IdentificationNotFound signifies an error when no identification is found with the given ID
{
"errors": [
{
"message": "Resource not found",
"long_message": "No resource was found for ID <resourceID>",
"code": "resource_not_found"
}
]
}
LastIdentificationDeletionFailed signifies an error when trying to delete the last identification associated with a user
{
"errors": [
{
"message": "Deletion failed",
"long_message": "You cannot delete your last identification.",
"code": "identification_deletion_failed"
}
]
}{
"errors": [
{
"message": "Update failed",
"long_message": "You cannot set your last identification as second factor.",
"code": "identification_update_failed"
}
]
}{
"errors": [
{
"message": "Deleting your last <sanitizedIdentType> is prohibited",
"long_message": "You are required to maintain at least one <sanitizedIdentType> in your account at all times",
"code": "last_required_identification_deletion_failed"
}
]
}{
"errors": [
{
"message": "Update failed",
"long_message": "Cannot update second factor attributes for unverified identification",
"code": "identification_update_second_factor_unverified"
}
]
}{
"errors": [
{
"message": "Image decode error",
"long_message": "The image could not be decoded. Please ensure the image is valid and try again.",
"code": "request_body_invalid"
}
]
}{
"errors": [
{
"message": "Image not found",
"long_message": "Image not found",
"code": "image_not_found"
}
]
}
ImageTooLarge signifies an error when the image being uploaded is too large to handle.
{
"errors": [
{
"message": "Image too large",
"long_message": "The image being uploaded is more than 10MB. Please choose a smaller one.",
"code": "image_too_large"
}
]
}{
"errors": [
{
"message": "Unsupported image type",
"long_message": "'<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.
{
"errors": [
{
"message": "Image file missing",
"long_message": "There was no image file present in the request",
"code": "form_param_missing"
}
]
}{
"errors": [
{
"message": "Impersonation limit exceeded",
"long_message": "Your application has reached the impersonation limit for your plan (<used>/<limit>). The limit will reset at the beginning of the next billing period.",
"code": "impersonation_limit_exceeded",
"meta": {
"limit": 0,
"used": 0
}
}
]
}{
"errors": [
{
"message": "is not allowed",
"long_message": "`<param>` isn't allowed to be set for this instance",
"code": "disabled_instance_restriction",
"meta": {
"param_name": "<param>"
}
}
]
}Instances
BreaksInstanceInvariant is returned when the change would break a rule that the
instance's user settings require.
{
"errors": [
{
"message": "Breaks instance invariant",
"long_message": "<invariantDescription> - This invariant is determined by your user settings",
"code": "breaks_instance_invariant"
}
]
}
InstanceNotFound signifies an error when no instance with the given ID was found
{
"errors": [
{
"message": "Instance not found",
"long_message": "No instance was found with id <instanceID>",
"code": "resource_not_found"
}
]
}{
"errors": [
{
"message": "Bad request",
"long_message": "Bad request",
"code": "bad_request"
}
]
}{
"errors": [
{
"message": "<message>",
"long_message": "<message>",
"code": "bad_request"
}
]
}
Conflict is returned when the request conflicts with the current state of the resource.
{
"errors": [
{
"message": "Conflict",
"long_message": "Conflict",
"code": "conflict"
}
]
}
403 - quota exceeded
{
"errors": [
{
"message": "Quota exceeded",
"long_message": "Quota exceeded, you have reached your limit.",
"code": "quota_exceeded"
}
]
}
409 - resource locked
{
"errors": [
{
"message": "resource busy",
"long_message": "This resource is currently being modified by another request. Please try again.",
"code": "resource_locked"
}
]
}
ServiceUnavailable is returned when the service is temporarily unavailable.
{
"errors": [
{
"message": "Service unavailable",
"long_message": "Service unavailable",
"code": "service_unavailable"
}
]
}
Unexpected is returned when the server hits an unexpected error.
{
"errors": [
{
"message": "Oops, an unexpected error occurred",
"long_message": "There was an internal error on our servers. We've been notified and are working on fixing it.",
"code": "internal_clerk_error"
}
]
}Invitations
DuplicateInvitations denotes an error when there are already invitations
for the given email addresses
{
"errors": [
{
"message": "duplicate invitation",
"long_message": "There are already pending invitations for the following email addresses: <emails>",
"code": "duplicate_record",
"meta": {
"email_addresses": [
"<emailAddresses>"
]
}
}
]
}
InvitationAlreadyAccepted denotes an error when someone tries to use
an invitation which is already accepted.
{
"errors": [
{
"message": "Invitation is already accepted, try signing in instead.",
"long_message": "Invitation is already accepted, try signing in instead.",
"code": "invitation_already_accepted"
}
]
}
InvitationAlreadyRevoked denotes an error when someone tries to revoke
an invitation which is already revoked.
{
"errors": [
{
"message": "Invitation is already revoked.",
"long_message": "Invitation is already revoked.",
"code": "invitation_already_revoked"
}
]
}
InvitationNotFound denotes an error when there is no invitation with
the given id
{
"errors": [
{
"message": "not found",
"long_message": "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
{
"errors": [
{
"message": "Invitations are only supported on instances that accept email addresses.",
"long_message": "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.
{
"errors": [
{
"message": "The invitation was revoked.",
"long_message": "The invitation was revoked.",
"code": "revoked_invitation"
}
]
}JWT templates
JWTTemplateNotFound signifies an error when a JWT template was not found by the provided attribute
{
"errors": [
{
"message": "JWT template not found",
"long_message": "No JWT template exists with <attribute>: <val>",
"code": "resource_not_found"
}
]
}
JWTTemplateReservedClaim denotes an error when the provided template contains a reserved claim.
{
"errors": [
{
"message": "reserved claim used",
"long_message": "You can't use the reserved claim: '<claim>'",
"code": "jwt_template_reserved_claim",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "session token template cannot be deleted",
"long_message": "This template cannot be deleted because it's a session token template",
"code": "session_token_jwt_template"
}
]
}Log drains
LogDrainConfigInvalidStateTransition returns a 409 error indicating the
requested lifecycle action is not legal from the log drain's current state
(e.g. pausing a drain that is not active). The from/to are state names.
{
"errors": [
{
"message": "Invalid log drain state transition",
"long_message": "A log drain in the \"<from>\" state cannot transition to \"<to>\".",
"code": "log_drain_config_invalid_state_transition"
}
]
}Machine token
MachineTokenReservedClaim denotes an error when the provided machine token claims object contains a reserved claim.
{
"errors": [
{
"message": "reserved claim used",
"long_message": "You can't use the reserved claim: '<claim>'",
"code": "machine_token_reserved_claim",
"meta": {
"param_name": "<param>"
}
}
]
}Network
GatewayTimeout signifies an error when a 3rd party service takes too long to respond.
{
"errors": [
{
"message": "Gateway Timeout",
"long_message": "A request to a 3rd party service timed out",
"code": "gateway_timeout"
}
]
}{
"errors": [
{
"message": "custom OAuth provider cannot use discovery URL",
"long_message": "The custom OAuth provider cannot use the discovery URL. Please provide the necessary configuration manually.",
"code": "custom_oauth_provider_cannot_use_discovery_url",
"meta": {
"param_name": "discovery_url"
}
}
]
}{
"errors": [
{
"message": "issuer mismatch in custom OAuth provider discovery URL",
"long_message": "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": {
"param_name": "discovery_url"
}
}
]
}{
"errors": [
{
"message": "error retrieving OAuth response from provider's discovery URL",
"long_message": "An error was encountered when attempting to retrieve metadata from the oauth url \"<url>\": \"<reason>\"",
"code": "custom_oauth_provider_discovery_server_retrieval_error",
"meta": {
"param_name": "discovery_url"
}
}
]
}
ExternalAccountEmailAddressVerificationRequired signifies an error when the external account requires email address verification
{
"errors": [
{
"message": "Email address verification required",
"long_message": "Your associated email address is required to be verified, because it was initially created as unverified.",
"code": "external_account_email_address_verification_required"
}
]
}{
"errors": [
{
"message": "Missing refresh token",
"long_message": "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 is returned when the external account from the OAuth
callback isn't found. It's also returned in transfer flows where the external
account exists but no user has been created for it yet.
{
"errors": [
{
"message": "Invalid external account",
"long_message": "The External Account was not found.",
"code": "external_account_not_found"
}
]
}{
"errors": [
{
"message": "Missing OAuth access token",
"long_message": "OAuth access token is missing",
"code": "oauth_missing_access_token"
}
]
}{
"errors": [
{
"message": "Cannot refresh OAuth access token",
"long_message": "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"
}
]
}
OAuthSharedCredentialsStoredTokenNotRetrievable signifies an error when a
caller attempts to retrieve a stored provider access token that was minted
with Clerk's shared development OAuth credentials, even though the provider
now uses custom credentials. The stored token cannot be exposed; the account
must be reconnected to reissue a token under the custom credentials.
{
"errors": [
{
"message": "Stored access token not retrievable",
"long_message": "This account's OAuth access token was issued with Clerk's shared development credentials and cannot be retrieved. Reconnect the account to reissue a token under your own OAuth credentials.",
"code": "oauth_shared_credentials_stored_token_not_retrievable"
}
]
}
OAuthSharedCredentialsTokenRetrievalNotSupported signifies an error when a
caller attempts to retrieve a provider access token while the provider is
currently configured to use Clerk's shared development OAuth credentials.
Retrieving raw provider tokens is only supported for custom OAuth credentials.
{
"errors": [
{
"message": "Access token retrieval not supported with shared credentials",
"long_message": "Retrieving the OAuth access token is not supported while using Clerk's shared development credentials. Configure custom OAuth credentials for this provider to retrieve access tokens.",
"code": "oauth_shared_credentials_token_retrieval_not_supported"
}
]
}{
"errors": [
{
"message": "OAuth provider not enabled",
"long_message": "Single-sign on for this OAuth provider is not enabled in the instance settings.",
"code": "oauth_token_provider_not_enabled"
}
]
}{
"errors": [
{
"message": "Token retrieval failed",
"long_message": "Failed to retrieve a new access token from the OAuth provider",
"code": "oauth_token_retrieval_error",
"meta": {
"provider_error": "<cause>"
}
}
]
}
UnsupportedOauthProvider signifies an error when an instance tries to enable
an OAuth external provider which is not supported.
{
"errors": [
{
"message": "<providerTitle> OAuth is not supported.",
"long_message": "<providerTitle> OAuth is not supported. Please contact us if you think this error should not appear.",
"code": "oauth_unsupported_provider"
}
]
}{
"errors": [
{
"message": "duplicate redirect URI",
"long_message": "the redirect URI already exists",
"code": "duplicate_record"
}
]
}{
"errors": [
{
"message": "consent screen cannot be disabled",
"long_message": "Consent screen cannot be disabled for a dynamically registered OAuth Application",
"code": "oauth_application_consent_screen_cannot_be_disabled"
}
]
}{
"errors": [
{
"message": "consent screen requires a consent path",
"long_message": "The consent screen cannot be enabled because there is no valid route to display it. The default consent page is hosted on the Account Portal, which is disabled for this instance, and no custom OAuth consent path has been configured. Configure an OAuth consent path or enable the Account Portal before enabling the consent screen.",
"code": "oauth_application_consent_screen_requires_consent_path"
}
]
}Organizations
400 - User with given identifier is already a member of the organization and cannot be added again
{
"errors": [
{
"message": "already a member",
"long_message": "<user> is already a member of the organization.",
"code": "already_a_member_in_organization"
}
]
}{
"errors": [
{
"message": "not found",
"long_message": "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.
{
"errors": [
{
"message": "exclusive organization membership",
"long_message": "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.
{
"errors": [
{
"message": "exclusive organization membership cannot be enabled",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "not allowed",
"long_message": "`force_organization_selection` cannot be enabled when organizations are disabled. Please enable organizations first.",
"code": "force_organization_selection_not_allowed_when_organizations_disabled"
}
]
}{
"errors": [
{
"message": "missing permission",
"long_message": "Current user is missing an organization permission.",
"code": "missing_organization_permission",
"meta": {
"permissions": [
"<permissions>"
]
}
}
]
}
NotAMemberInOrganization is returned when the user isn't a member of the
organization and the action is limited to its members.
{
"errors": [
{
"message": "not a member",
"long_message": "Current user is not a member of the organization. Only organization members can perform this action.",
"code": "not_a_member_in_organization"
}
]
}{
"errors": [
{
"message": "this organization already has an SSO connection",
"long_message": "This organization already has an SSO connection.",
"code": "organization_already_has_sso_connection",
"meta": {
"param_name": "organization_id"
}
}
]
}
400 - Creator doesn't exist
{
"errors": [
{
"message": "creator not found",
"long_message": "No users found with id <userID>.",
"code": "organization_creator_not_found"
}
]
}{
"errors": [
{
"message": "organizaton domain already exists",
"long_message": "This domain is already used by another organization.",
"code": "organization_domain_already_exists",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "organization domain already exists",
"long_message": "This domain is already used by your organization.",
"code": "organization_domain_already_exists_same_organization",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "blocked email domain",
"long_message": "This is a blocked email provider domain. Please use a different one.",
"code": "organization_domain_blocked",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "common email domain",
"long_message": "This is a common email provider domain. Please use a different one.",
"code": "organization_domain_common",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "organization enrollment mode not enabled",
"long_message": "Enrollment mode <enrollmentMode> is not enabled for this instances's organizations.",
"code": "organization_domain_enrollment_mode_not_enabled"
}
]
}{
"errors": [
{
"message": "domain used for organization enrollment",
"long_message": "This domain is already used for organization enrollment with verified domains. Please use a different one.",
"code": "organization_domain_exists_for_enrollment"
}
]
}{
"errors": [
{
"message": "domain exists for an organization enterprise connection",
"long_message": "This domain is already used for your organization’s SSO. Please use a different one.",
"code": "organization_domain_exists_for_enterprise_connection"
}
]
}{
"errors": [
{
"message": "organization domains quota exceeded",
"long_message": "You have reached your limit of <maxAllowed> domains per organization.",
"code": "organization_domain_quota_exceeded"
}
]
}{
"errors": [
{
"message": "organization domains not enabled",
"long_message": "This instance does not have domains enabled for organizations.",
"code": "organization_domains_not_enabled"
}
]
}{
"errors": [
{
"message": "organization role sets for instance quota exceeded",
"long_message": "You have reached your limit of <maxAllowed> organization role sets per instance.",
"code": "organization_instance_role_sets_quota_exceeded"
}
]
}{
"errors": [
{
"message": "organization roles for instance quota exceeded",
"long_message": "You have reached your limit of <maxAllowed> organization roles per instance.",
"code": "organization_instance_roles_quota_exceeded"
}
]
}{
"errors": [
{
"message": "invitation has already been accepted",
"long_message": "This invitation has already been accepted. Sign in instead.",
"code": "organization_invitation_already_accepted"
}
]
}
404 - Invitation is not pending.
{
"errors": [
{
"message": "not pending",
"long_message": "The organization invitation is not in the 'pending' status.",
"code": "organization_invitation_not_pending"
}
]
}{
"errors": [
{
"message": "organization invitation not unique",
"long_message": "Organizations cannot have duplicate pending invitations for an email address.",
"code": "organization_invitation_not_unique"
}
]
}{
"errors": [
{
"message": "invitation has been revoked",
"long_message": "This invitation has been revoked and cannot be used anymore.",
"code": "organization_invitation_revoked_code"
}
]
}
OrganizationMemberLimitManagedByBilling returns an error when trying to update
the member limit for an organization that is on a seat-based billing plan
{
"errors": [
{
"message": "member limit managed by Billing",
"long_message": "This organization's member limit is managed by their subscription. It cannot be edited directly.",
"code": "organization_member_limit_managed_by_billing",
"meta": {
"param_name": "max_allowed_memberships"
}
}
]
}{
"errors": [
{
"message": "organization membership quota exceeded",
"long_message": "You have reached your limit of <maxAllowed> organization memberships, including outstanding invitations.",
"code": "organization_membership_quota_exceeded"
}
]
}{
"errors": [
{
"message": "organization membership quota exceeded for sso per org",
"long_message": "The organization you are trying to join is full. Please contact support.",
"code": "organization_membership_quota_exceeded_for_sso"
}
]
}{
"errors": [
{
"message": "membership role managed by directory sync",
"long_message": "This membership is managed by a directory and cannot be changed manually.",
"code": "organization_membership_managed_by_scim"
}
]
}{
"errors": [
{
"message": "minimum organization permissions needed",
"long_message": "There has to be at least one organization member with the minimum required permissions",
"code": "organization_minimum_permissions_needed"
}
]
}{
"errors": [
{
"message": "missing permissions for creator role",
"long_message": "The creator role must contain the following permissions: <permissionKeys>",
"code": "organization_missing_creator_role_permissions"
}
]
}{
"errors": [
{
"message": "invalid organization name",
"long_message": "The organization name \"<name>\" is invalid: <reason>",
"code": "form_param_value_invalid",
"meta": {
"param_name": "name"
}
}
]
}{
"errors": [
{
"message": "access denied",
"long_message": "The organizations feature is not enabled for this instance. You can enable it at https://dashboard.clerk.com.",
"code": "organization_not_enabled_in_instance"
}
]
}
OrganizationNotFound returns a 404 when an organization does not exist.
{
"errors": [
{
"message": "not found",
"long_message": "Given organization not found.",
"code": "resource_not_found"
}
]
}
OrganizationNotFoundOrUnauthorized is returned when the organization doesn't
exist or the caller can't access it. The response doesn't say which, so it
doesn't reveal whether the organization exists.
{
"errors": [
{
"message": "not found or unauthorized",
"long_message": "Given organization not found, or you don't have permission to access the organization",
"code": "organization_not_found_or_unauthorized"
}
]
}{
"errors": [
{
"message": "not found",
"long_message": "Organization permission not found",
"code": "resource_not_found"
}
]
}{
"errors": [
{
"message": "organization quota exceeded",
"long_message": "You have reached your limit of <maxAllowed> organizations. You can remove the organization limit by upgrading to a paid plan or using a production instance.",
"code": "organization_quota_exceeded"
}
]
}{
"errors": [
{
"message": "role is assigned to organization members",
"long_message": "The organization role is currently assigned to one or more organization members.",
"code": "organization_role_assigned_members"
}
]
}{
"errors": [
{
"message": "role exists in pending organization invitations",
"long_message": "The organization role exists in one or more pending organization invitations. Please revoke these invitations to proceed.",
"code": "organization_role_exists_in_invitations"
}
]
}{
"errors": [
{
"message": "not found",
"long_message": "Organization role not found",
"code": "resource_not_found",
"meta": {
"param_name": "<paramName>"
}
}
]
}{
"errors": [
{
"message": "role is assigned to users",
"long_message": "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": {
"role_key": "<roleKey>"
}
}
]
}{
"errors": [
{
"message": "permission already assigned to role",
"long_message": "This organization permission is already associated to this organization role.",
"code": "organization_role_permission_association_exists"
}
]
}{
"errors": [
{
"message": "permission not assigned to role",
"long_message": "This organization permission is not associated with the organization role.",
"code": "organization_role_permission_association_not_found"
}
]
}{
"errors": [
{
"message": "contact support",
"long_message": "This reassignment affects <affectedCount> memberships, contact support to complete this operation",
"code": "organization_role_set_reassignment_contact_support"
}
]
}{
"errors": [
{
"message": "reassignment mappings invalid",
"long_message": "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": {
"role_key": "<roleKey>"
}
}
]
}{
"errors": [
{
"message": "reassignment mappings missing",
"long_message": "The following roles are missing from the reassignment mappings: <roleKeys>",
"code": "organization_role_set_reassignment_mappings_missing",
"meta": {
"role_keys": [
"<roleKeys>"
]
}
}
]
}{
"errors": [
{
"message": "role is used as the creator role",
"long_message": "The organization role cannot be deleted as it is currently used as the creator role.",
"code": "organization_role_default_creator_role"
}
]
}{
"errors": [
{
"message": "role is used as the domain default role",
"long_message": "The organization role cannot be deleted as it is currently used as the default domain role.",
"code": "organization_role_domain_default_role"
}
]
}
403 - Organizations cannot be enabled for this workspace.
{
"errors": [
{
"message": "Organizations cannot be enabled for this workspace.",
"long_message": "Organizations cannot be enabled for this workspace.",
"code": "organizations_cannot_be_enabled"
}
]
}{
"errors": [
{
"message": "cannot disable organizations",
"long_message": "Cannot disable organizations because <reason>.",
"code": "organizations_disable_not_allowed"
}
]
}{
"errors": [
{
"message": "organization slugs not enabled",
"long_message": "This instance does not have slugs enabled for organizations.",
"code": "organization_slugs_disabled"
}
]
}{
"errors": [
{
"message": "organization system permission cannot be modified",
"long_message": "This organization permission cannot be modified because it is a system permission.",
"code": "organization_system_permission_not_modifiable"
}
]
}{
"errors": [
{
"message": "Organization too large",
"long_message": "Organization size is above the API limit",
"code": "organization_too_large",
"meta": {
"param_name": "organization_id"
}
}
]
}
403 - Organization Creation Limit Exceeded
{
"errors": [
{
"message": "Organization Creation Limit Exceeded",
"long_message": "You have exceeded the maximum number of organizations you can create.",
"code": "org_creation_limit_exceeded"
}
]
}{
"errors": [
{
"message": "personal accounts are not allowed",
"long_message": "You must maintain at least one organization membership since personal accounts are not allowed on the application",
"code": "personal_accounts_not_allowed"
}
]
}{
"errors": [
{
"message": "migration in progress",
"long_message": "Cannot modify role set while role reassignment is in progress. Please wait for the migration to complete.",
"code": "role_migration_in_progress"
}
]
}{
"errors": [
{
"message": "not registered",
"long_message": "Passkey is not registered.",
"code": "passkey_not_registered"
}
]
}Platform
PlatformAPIAuthStrategyNotAllowed signifies that the endpoint does not accept the authentication strategy used for the request.
{
"errors": [
{
"message": "Authentication method not allowed",
"long_message": "This endpoint does not accept the credential type used. Use an authentication method allowed for this operation.",
"code": "platform_api_auth_strategy_not_allowed"
}
]
}{
"errors": [
{
"message": "Unsupported plan features",
"long_message": "Some features are not supported in your current plan. Upgrade your subscription to unlock them.",
"code": "unsupported_subscription_plan_features",
"meta": {
"unsupported_features": [
"<unsupportedFeatures>"
]
}
}
]
}Promo codes
CheckoutPromoCodeInvalid is returned when a promo code entered at checkout
can't be applied: the code doesn't exist, is archived, its discount's
redemption window isn't open, or the discount doesn't target this checkout's
price, period, or currency. The response doesn't say which, so codes can't be
probed. Show it as a single "Invalid promo code" state.
{
"errors": [
{
"message": "Invalid promo code",
"long_message": "This promo code cannot be applied to this checkout",
"code": "checkout_promo_code_invalid",
"meta": {
"param_name": "<paramName>"
}
}
]
}Public keys
PublicKeyNotFound signifies an error when no public key was found with the given id
{
"errors": [
{
"message": "Public key not found",
"long_message": "No public key was found with id <publicKeyID>",
"code": "resource_not_found"
}
]
}Redirect URLs
RedirectURLNotFound signifies an error when a RedirectURL was not found by the provided attribute
{
"errors": [
{
"message": "Redirect url not found",
"long_message": "No RedirectURL exists with <attribute>: <val>",
"code": "resource_not_found"
}
]
}{
"errors": [
{
"message": "bulk size exceeded",
"long_message": "Parameters exceed the maximum allowed bulk processing size of <MaxBulkSize>.",
"code": "bulk_size_exceeded"
}
]
}
FailedToParseRequestBody is returned when a field in the request body has the wrong type.
{
"errors": [
{
"message": "is invalid",
"long_message": "<field> is invalid. Received <value>, must be of type <typeName>.",
"code": "form_param_value_invalid",
"meta": {
"param_name": "<Field>"
}
}
]
}{
"errors": [
{
"message": "Infinite redirect loop detected",
"long_message": "Infinite redirect loop detected. That usually means that we were not able to determine the auth state for this request.",
"code": "infinite_redirect_loop"
}
]
}{
"errors": [
{
"message": "invalid API version",
"long_message": "Invalid Clerk API version: <reason>",
"code": "api_version_invalid"
}
]
}
InvalidJSONRequestBody is returned when the request body is malformed JSON. The
long message says what's wrong, such as the byte offset of a syntax error.
{
"errors": [
{
"message": "Request body invalid",
"long_message": "Invalid JSON at byte offset <offset>",
"code": "request_body_invalid"
}
]
}
InvalidRequestBody signifies an error when the body of the request does not conform to the expected format
{
"errors": [
{
"message": "Request body invalid",
"long_message": "The request body is invalid. Please consult the API documentation for more information.",
"code": "request_body_invalid"
}
]
}{
"errors": [
{
"message": "Malformed publishable key",
"long_message": "Ensure the provided publishable key (<key>) is the one displayed in Dashboard",
"code": "malformed_publishable_key"
}
]
}
MalformedRequestParameters signifies an error when the request parameters are malformed and result in parsing errors
{
"errors": [
{
"message": "Malformed request parameters",
"long_message": "The request parameters are malformed and could not be parsed",
"code": "malformed_request_parameters"
}
]
}{
"errors": [
{
"message": "Missing query parameter",
"long_message": "Either of the following query parameters must be provided: <parameters>.",
"code": "missing_query_parameter"
}
]
}
MissingQueryParameter is returned when the request is missing a required query parameter.
{
"errors": [
{
"message": "Missing query parameter '<param>'",
"long_message": "The query parameter '<param>' is missing from the request. Please consult the API documentation for more information.",
"code": "missing_query_parameter"
}
]
}{
"errors": [
{
"message": "Request body too large",
"long_message": "The request body exceeds the maximum allowed size of <maxBytes> bytes.",
"code": "request_body_too_large"
}
]
}
UnsupportedContentType signifies an error when provided content type is unsupported
{
"errors": [
{
"message": "Content-Type is unsupported",
"long_message": "Content-Type <actual> is unsupported. You should use <expected> instead.",
"code": "unsupported_content_type"
}
]
}{
"errors": [
{
"message": "SAML Connection can't be activated",
"long_message": "You have to provide the <fields> before you are able to activate this connection.",
"code": "saml_connection_cant_be_activated"
}
]
}{
"errors": [
{
"message": "Failed to fetch IdP metadata",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "Failed to parse IdP metadata",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "IdP metadata is missing required fields",
"long_message": "The IdP metadata is missing the following required fields: <fields>",
"code": "saml_metadata_missing_fields",
"meta": {
"missing_fields": [
"<missingFields>"
]
}
}
]
}SCIM
SCIMAttributeManagedByDirectory returns a 409 Conflict error when attempting to
update an attribute that is managed by a directory.
{
"errors": [
{
"message": "attribute managed by directory sync",
"long_message": "<attributeDescription> is not allowed to be updated. This attribute is managed by the directory.",
"code": "attribute_managed_by_scim",
"meta": {
"param_name": "<paramName>"
}
}
]
}
SCIMDirectoryDisabled returns an error when attempting to trigger a pull
sync on a disabled directory.
{
"errors": [
{
"message": "directory disabled",
"long_message": "This directory is disabled.",
"code": "scim_directory_disabled"
}
]
}{
"errors": [
{
"message": "enterprise connection already in use",
"long_message": "This enterprise connection is already associated with another directory.",
"code": "scim_directory_enterprise_connection_already_used",
"meta": {
"param_name": "scim_connection_id"
}
}
]
}
SCIMDirectoryOrganizationAlreadyUsed is returned when creating a SCIM directory
for an organization that already has one.
{
"errors": [
{
"message": "organization already has a SCIM directory",
"long_message": "This organization is already associated with another SCIM directory.",
"code": "scim_directory_organization_already_used",
"meta": {
"param_name": "<paramName>"
}
}
]
}
SCIMDirectoryPullModeNotConfigured returns an error when attempting to
trigger a pull sync on a directory that is not configured for
pull-mode sync.
{
"errors": [
{
"message": "directory not configured for pull-mode sync",
"long_message": "This directory is not configured for pull-mode sync.",
"code": "scim_directory_pull_mode_not_configured"
}
]
}
SCIMDirectorySyncThrottled returns a 409 Conflict error when a manual pull
sync is requested while one is already running or another just started.
{
"errors": [
{
"message": "sync already in progress",
"long_message": "A sync for this directory is already running.",
"code": "scim_directory_sync_throttled"
}
]
}
SCIMGroupNotFoundInDirectory returns a validation error for a group ID that
cannot be found in the requested directory.
{
"errors": [
{
"message": "group not found in directory",
"long_message": "Group \"<groupID>\" was not found in directory \"<directoryID>\". Retrieve the current group IDs using GET /v1/directories/<directoryID>/groups and retry with a group ID from this directory.",
"code": "form_param_value_invalid",
"meta": {
"param_name": "scim_group_id"
}
}
]
}{
"errors": [
{
"message": "expired session token consumed",
"long_message": "The provided expired session token was already consumed in a previous refresh request",
"code": "session_refresh_expired_session_token_consumed"
}
]
}{
"errors": [
{
"message": "Invalid expired_token param",
"long_message": "The session token provided could not be successfully verified",
"code": "expired_session_token_invalid"
}
]
}{
"errors": [
{
"message": "session token too old",
"long_message": "The provided expired session token is too old",
"code": "session_refresh_expired_session_token_too_old"
}
]
}{
"errors": [
{
"message": "session inactive",
"long_message": "The provided session is not active",
"code": "session_refresh_inactive_session"
}
]
}{
"errors": [
{
"message": "expired session token ineligible",
"long_message": "The provided expired session token is not eligible for refresh",
"code": "session_refresh_session_token_ineligible"
}
]
}{
"errors": [
{
"message": "Request origin is invalid",
"long_message": "The request_origin parameter could not be parsed",
"code": "refresh_request_origin_invalid"
}
]
}{
"errors": [
{
"message": "missing 'azp' claim",
"long_message": "No 'azp' claim present in the provided expired session token",
"code": "expired_session_token_missing_azp"
}
]
}{
"errors": [
{
"message": "missing 'iat' claim",
"long_message": "No 'iat' claim present in the provided expired session token",
"code": "session_refresh_expired_session_token_missing_iat"
}
]
}{
"errors": [
{
"message": "missing 'sid' claim",
"long_message": "No 'sid' claim present in the provided expired session token",
"code": "expired_session_token_missing_sid"
}
]
}{
"errors": [
{
"message": "Request origin does not match azp claim",
"long_message": "The request_origin parameter does not match the 'azp' claim of expired_token",
"code": "refresh_request_origin_azp_mismatch"
}
]
}{
"errors": [
{
"message": "Session not found",
"long_message": "No session was found with id <sessionID>",
"code": "session_refresh_session_not_found"
}
]
}{
"errors": [
{
"message": "Session ID does not match the 'sid' claim",
"long_message": "The 'sid' claim of the provided expired session token does not match the session ID provided in the request path",
"code": "refresh_sid_mismatch"
}
]
}{
"errors": [
{
"message": "Refresh token not found",
"long_message": "The provided refresh token was not found",
"code": "refresh_token_not_found"
}
]
}{
"errors": [
{
"message": "user not found",
"long_message": "The provided user was not found",
"code": "session_refresh_user_not_found"
}
]
}{
"errors": [
{
"message": "unable to create session",
"long_message": "Unable to create new session when an impersonation session is present. Please sign out first.",
"code": "session_creation_not_allowed"
}
]
}{
"errors": [
{
"message": "account deprovisioned",
"long_message": "Your account is deprovisioned",
"code": "deprovisioned"
}
]
}{
"errors": [
{
"message": "account deprovisioned",
"long_message": "The target user's account has been deprovisioned according to their external identity provider",
"code": "deprovisioned"
}
]
}{
"errors": [
{
"message": "Invalid session token",
"long_message": "The token provided could not be successfully verified",
"code": "invalid_session_token"
}
]
}
ReverificationNotFound signifies an error when no reverification (step-up) with the given id was found on the session
{
"errors": [
{
"message": "Reverification not found",
"long_message": "No reverification was found with id <reverificationID>",
"code": "resource_not_found"
}
]
}
SessionNotFound signifies an error when no session with the given ID was found
{
"errors": [
{
"message": "Session not found",
"long_message": "No session was found with id <sessionID>",
"code": "resource_not_found"
}
]
}Sign-in
IdentificationClaimed signifies an error when the requested identification is already claimed by another user
{
"errors": [
{
"message": "Identification claimed by another user",
"long_message": "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
{
"errors": [
{
"message": "Invalid action",
"long_message": "We were unable to complete <action> for this Client. <resolution>",
"code": "client_state_invalid"
}
]
}{
"errors": [
{
"message": "cannot revoke",
"long_message": "Sign in token cannot be revoked because its status is <status>. Only pending tokens can be revoked.",
"code": "sign_in_token_cannot_be_revoked_code"
}
]
}{
"errors": [
{
"message": "is not allowed",
"long_message": "`<param>` isn't allowed to be `<value>` when sign-up mode is set to <mode>",
"code": "sign_up_mode_restricted_invalid_value",
"meta": {
"param_name": "<param>"
}
}
]
}{
"errors": [
{
"message": "Sign up cannot be updated",
"long_message": "This sign up has reached a terminal state and cannot be updated",
"code": "sign_up_cannot_be_updated"
}
]
}Signing keys
SigningKeyNotFound signifies an error when no signing key with the given ID was found
{
"errors": [
{
"message": "Signing key not found",
"long_message": "No signing key was found with id <signingKeyID>",
"code": "resource_not_found"
}
]
}SMS
DevMonthlySMSLimitExceeded signifies an error when an SMS sending attempt is made while the development limit has already been reached
{
"errors": [
{
"message": "Development monthly SMS limit exceeded",
"long_message": "Operation cannot be completed because the monthly limit for SMS messages in development (<limit>) has been reached.",
"code": "dev_monthly_sms_limit_exceeded",
"meta": {
"dev_monthly_sms_limit": 0
}
}
]
}
SMSCountryRemovalRestricted signals that the caller tried to remove one or more
tier B-F countries from the SMS blocklist on an instance whose plan lacks the
phone_code feature. Removing those countries is restricted to prevent SMS pumping abuse on
free/dev instances; activating them requires upgrading the plan or contacting support.
{
"errors": [
{
"message": "SMS country removal restricted",
"long_message": "Cannot remove the following countries from the SMS blocklist without an upgraded plan: <countryCodes>. Contact support to activate these countries.",
"code": "sms_country_removal_restricted",
"meta": {
"country_codes": [
"<countryCodes>"
]
}
}
]
}{
"errors": [
{
"message": "Sending SMS failed",
"long_message": "Sending SMS failed. Please contact support or try again later.",
"code": "sms_send_error"
}
]
}{
"errors": [
{
"message": "WhatsApp channel not enabled",
"long_message": "The 'whatsapp' channel is not available for this instance.",
"code": "whatsapp_channel_not_enabled",
"meta": {
"param_name": "channel"
}
}
]
}{
"errors": [
{
"message": "Invalid template body",
"long_message": "This template body is invalid and cannot be rendered successfully, please check for syntax errors",
"code": "invalid_template_body",
"meta": {
"param_name": "body"
}
}
]
}{
"errors": [
{
"message": "should contain {{<requiredVariable>}} variable",
"long_message": "Body should contain the {{<requiredVariable>}} variable",
"code": "required_variable_missing",
"meta": {
"param_name": "body"
}
}
]
}{
"errors": [
{
"message": "Template body cannot be modified",
"long_message": "The body of template with slug <slug> can't be modified",
"code": "template_body_modification_restricted"
}
]
}
TemplateDeletionRestricted signifies an error when a deletion is attempted for a built-in (non-custom) template
{
"errors": [
{
"message": "Template deletion restricted",
"long_message": "Template with slug <slug> can't be deleted",
"code": "template_deletion_restricted"
}
]
}
TemplateNotFound signifies an error when no template with given slug was found
{
"errors": [
{
"message": "Template not found",
"long_message": "No template was found with slug <slug>",
"code": "resource_not_found"
}
]
}
TemplateRevertRestricted signifies an error when a custom template is attempted to be reverted
{
"errors": [
{
"message": "Template revert restricted",
"long_message": "Template with slug <slug> can't be reverted",
"code": "template_revert_error"
}
]
}
TemplateTypeUnsupported signifies an error when an invalid template type is provided
{
"errors": [
{
"message": "Template type not supported",
"long_message": "Template type <templateType> is not supported",
"code": "template_type_unsupported"
}
]
}{
"errors": [
{
"message": "invalid TOTP secret",
"long_message": "The TOTP secret is invalid, please provide a valid one base32 encoded",
"code": "invalid_totp_secret_code"
}
]
}{
"errors": [
{
"message": "Insecure URL",
"long_message": "Please provide a secure URL (https)",
"code": "insecure_url",
"meta": {
"param_name": "<paramName>"
}
}
]
}{
"errors": [
{
"message": "not found",
"long_message": "Resource not found",
"code": "resource_not_found"
}
]
}Users
DeleteLinkedCommNotAllowed signifies an error when trying to delete a linked communication
{
"errors": [
{
"message": "Deleting a linked email address is not allowed",
"long_message": "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"
}
]
}{
"errors": [
{
"message": "incorrect password",
"long_message": "The provided password is not the one the user has set",
"code": "incorrect_password"
}
]
}{
"errors": [
{
"message": "incorrect TOTP",
"long_message": "The provided TOTP code is incorrect",
"code": "totp_incorrect_code"
}
]
}{
"errors": [
{
"message": "invalid length",
"long_message": "The provided TOTP code must be 6 characters long.",
"code": "totp_invalid_length"
}
]
}{
"errors": [
{
"message": "no password set",
"long_message": "This user does not have a password set for their account",
"code": "no_password_set"
}
]
}{
"errors": [
{
"message": "password disabled",
"long_message": "Password is disabled for this instance. Cannot force a password reset.",
"code": "password_disabled"
}
]
}{
"errors": [
{
"message": "TOTP is disabled",
"long_message": "This user does not have TOTP enabled in their account",
"code": "totp_disabled"
}
]
}
UserBanned signifies an error when a user is banned
{
"errors": [
{
"message": "User banned",
"long_message": "You have been banned. If you think this was by mistake, please contact support.",
"code": "user_banned"
}
]
}{
"errors": [
{
"message": "missing data",
"long_message": "\"<missingParams>\" data doesn't match user requirements set for this instance",
"code": "form_data_missing",
"meta": {
"param_names": [
"<missingParams>"
]
}
}
]
}{
"errors": [
{
"message": "User deactivated",
"long_message": "You have been deactivated. Please contact support.",
"code": "user_deactivated"
}
]
}
UserNotFound signifies an error when no user is found with the given ID
{
"errors": [
{
"message": "not found",
"long_message": "No user was found with id <userID>",
"code": "resource_not_found"
}
]
}{
"errors": [
{
"message": "user quota exceeded",
"long_message": "You have reached your limit of <maxAllowed> users. <resolution>",
"code": "user_quota_exceeded"
}
]
}{
"errors": [
{
"message": "user managed by directory sync",
"long_message": "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
{
"errors": [
{
"message": "already verified",
"long_message": "This verification has already been verified.",
"code": "verification_already_verified"
}
]
}
VerificationCodeNotSent is an attempt against a verification whose code
never went out: the send failed after the prepare had already returned. Tell
the user to request a new code rather than that theirs is incorrect.
{
"errors": [
{
"message": "Verification code was not sent",
"long_message": "We could not send a verification code for this request. Please request a new code.",
"code": "verification_code_not_sent"
}
]
}
VerificationCodeTooManyAttempts is the SMS provider declining to check the
code; no attempt was counted. The wait travels in Retry-After.
{
"errors": [
{
"message": "Too many verification attempts",
"long_message": "Too many attempts to verify this code. Please wait before trying again.",
"code": "verification_code_too_many_attempts"
}
]
}{
"errors": [
{
"message": "Too many verification code requests",
"long_message": "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
{
"errors": [
{
"message": "expired",
"long_message": "This verification has expired. You must create a new one.",
"code": "verification_expired"
}
]
}
VerificationFailed signifies an error when verification fails
{
"errors": [
{
"message": "failed",
"long_message": "Too many failed attempts. You have to try again with the same or another method.",
"code": "verification_failed"
}
]
}
VerificationInvalidStrategy signifies an error when the given strategy is not valid for current verification
{
"errors": [
{
"message": "has invalid strategy",
"long_message": "The strategy is not valid for the current verification.",
"code": "verification_strategy_invalid"
}
]
}
VerificationNotSent signifies an error when verification email was not sent
{
"errors": [
{
"message": "not sent",
"long_message": "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
{
"errors": [
{
"message": "Unknown verification status",
"long_message": "Found unknown verification status <status>",
"code": "verification_status_unknown"
}
]
}{
"errors": [
{
"message": "Waitlist entry already completed",
"long_message": "The waitlist entry has already been completed.",
"code": "waitlist_entry_already_completed"
}
]
}{
"errors": [
{
"message": "Waitlist entry already invited",
"long_message": "The waitlist entry has already been invited.",
"code": "waitlist_entry_already_invited"
}
]
}{
"errors": [
{
"message": "Waitlist entry already rejected",
"long_message": "The waitlist entry has already been rejected.",
"code": "waitlist_entry_already_rejected"
}
]
}{
"errors": [
{
"message": "Waitlist entry is locked",
"long_message": "This waitlist entry is locked and cannot be modified at this time. Please try again later.",
"code": "waitlist_entry_locked"
}
]
}{
"errors": [
{
"message": "Only one Svix app is allowed per instance.",
"long_message": "Only one Svix app is allowed per instance.",
"code": "svix_app_exists"
}
]
}{
"errors": [
{
"message": "Svix app creation failed",
"long_message": "Could not create a Svix app with name <name> at this time. Please contact us if this error persists.",
"code": "svix_app_create_error"
}
]
}{
"errors": [
{
"message": "No Svix apps are associated with the current instance.",
"long_message": "No Svix apps are associated with the current instance.",
"code": "svix_app_missing"
}
]
}Feedback
Last updated on