认证

错误代码

了解认证错误代码及其解决方法

认证错误代码

在使用 Supabase 认证 API 时，可能会返回各种错误。本指南将介绍如何在不同编程语言中有效处理这些错误。

错误类型

Supabase Auth 错误主要分为两大类：

  • API 错误：源自 Supabase Auth API
  • 客户端错误：源自客户端库的状态

不同语言的客户端错误有所差异，请参考下方对应章节：

所有源自客户端库 supabase.auth 命名空间的错误都会被 AuthError 类包装。

错误对象分为几个类别：

  • AuthApiError —— 源自 Supabase Auth API 的错误
    • 使用 isAuthApiError 而非 instanceof 检查来判断捕获的错误是否属于此类型
  • CustomAuthError —— 通常源自客户端库状态的错误
    • 使用错误的 name 属性来识别接收到的错误类别

归类为 AuthApiError 的服务器 API 错误始终包含 code 属性，可用于识别服务器返回的错误。同时存在 status 属性，表示响应中接收到的 HTTP 状态码。

HTTP 状态码

以下是您在 Supabase Auth 中最可能遇到的 HTTP 状态码及其含义：

403 禁止访问

在极少数情况下，当某个 Auth 功能对用户不可用，而开发者未检查该 API 是否对用户可用时返回此状态码。

422 无法处理的实体

当 API 请求被接受但无法处理时返回，通常因为用户或 Auth 服务器处于无法满足请求的状态。

429 请求过多

当 API 的速率限制被突破时返回。您应该经常处理此状态码，特别是在用户认证相关的函数中。

500 服务器内部错误

表示 Auth 服务器服务降级。最常见的原因是数据库设置问题，例如模式、函数、视图或其他数据库对象上的触发器行为异常。

501 未实现

当尝试使用需要特定功能的 API，但该功能未在 Auth 服务器上启用时返回。

认证错误代码表

下表提供了使用 Supabase Auth 时可能遇到的完整错误代码列表。每个错误代码都与特定问题相关联，并包含描述以帮助您高效理解和解决问题。

为了补充HTTP状态码，Supabase身份验证会返回一个字符串错误代码，让您更深入了解出错原因。这些代码是稳定的，可用于向用户展示国际化的错误信息。

代码描述
anonymous_provider_disabled匿名登录已禁用。
bad_code_verifier从PKCE流程返回，表明提供的代码验证器与预期的不匹配。这表明客户端库的实现存在问题。
bad_json通常在请求的HTTP主体不是有效的JSON格式时使用。
bad_jwt在Authorization标头中发送的JWT无效。
bad_oauth_callback从身份验证提供程序到身份验证服务的OAuth回调缺少所有必需的属性（状态）。这表明OAuth提供程序或客户端库实现存在问题。
bad_oauth_stateOAuth状态（OAuth提供程序回显给Supabase身份验证的信息）格式不正确。这表明OAuth提供程序集成存在问题。
captcha_failedCAPTCHA挑战无法通过CAPTCHA提供程序验证。请检查您的CAPTCHA集成。
conflict一般数据库冲突，例如对不应并发修改的资源进行并发请求。当用户同时发起过多的会话刷新请求时，经常会出现这种情况。请检查您的应用程序是否存在并发问题，如果检测到，请按指数方式退避。
email_address_invalid目前不支持示例和测试域名。请使用其他电子邮件地址。
email_address_not_authorized由于您的项目使用默认SMTP服务，不允许向此地址发送电子邮件。电子邮件只能发送给您Supabase组织中的成员。如果您想向其他人发送电子邮件，请设置自定义SMTP提供程序。
email_conflict_identity_not_deletable取消链接此身份会导致用户账户更改为已被另一个用户账户使用的电子邮件地址。这表明用户有两个不同的账户使用不同的主要电子邮件地址。在这种情况下，您可能需要将用户数据迁移到其中一个账户。
email_exists电子邮件地址已在系统中存在。
email_not_confirmed由于电子邮件地址未确认，不允许此用户登录。
email_provider_disabled电子邮件和密码注册已禁用。
flow_state_expired与API请求相关的PKCE流程状态已过期。请用户重新登录。
flow_state_not_found与API请求相关的PKCE流程状态不再存在。流程状态会在一段时间后过期并逐步清理，这可能会导致此错误。重试请求也可能导致此错误，因为之前的请求可能已销毁流程状态。请用户重新登录。
hook_payload_invalid_content_type来自身份验证的有效负载没有有效的Content-Type标头。
hook_payload_over_size_limit来自身份验证的有效负载超过最大大小限制。
hook_timeout无法在分配的最长时间内到达钩子。
hook_timeout_after_retry经过最大重试次数后仍无法到达钩子。
identity_already_exists与API相关的身份已链接到一个用户。
identity_not_found与API调用相关的身份不存在，例如身份被取消链接或删除时。
insufficient_aal要调用此API，用户必须具有更高的身份验证器保证级别。要解决此问题，请用户完成多因素身份验证挑战。
invite_not_found邀请已过期或已被使用。
invalid_credentials登录凭据或授权类型未被识别。
manual_linking_disabled在身份验证服务器上未启用调用supabase.auth.linkUser()及相关API。
mfa_challenge_expired对多因素身份验证挑战的响应应在固定时间段内完成。遇到此错误时，请请求新的挑战。
mfa_factor_name_conflict单个用户的多因素身份验证因素不应具有相同的友好名称。
mfa_factor_not_found多因素身份验证因素不再存在。
mfa_ip_address_mismatch多因素身份验证因素的注册过程必须在相同的IP地址开始和结束。
mfa_phone_enroll_not_enabled多因素身份验证电话因素的注册已禁用。
mfa_phone_verify_not_enabled通过电话因素登录和新电话因素的验证已禁用。
mfa_totp_enroll_not_enabled多因素身份验证TOTP因素的注册已禁用。
mfa_totp_verify_not_enabled通过TOTP因素登录和新TOTP因素的验证已禁用。
mfa_verification_failed多因素身份验证挑战无法验证 - TOTP代码错误。
mfa_verification_rejected进一步的多因素身份验证被拒绝。仅当多因素身份验证验证尝试钩子返回拒绝决定时才会返回此错误。
mfa_verified_factor_exists用户已存在已验证的电话因素。请取消注册现有的已验证电话因素以继续。
mfa_web_authn_enroll_not_enabled多因素身份验证Web Authn因素的注册已禁用。
mfa_web_authn_verify_not_enabled通过WebAuthn因素登录和新WebAuthn因素的验证已禁用。
no_authorization此HTTP请求需要Authorization标头，但未提供。
not_admin访问API的用户不是管理员，即JWT中不包含将其标识为身份验证服务器管理员的role声明。
oauth_provider_not_supported使用的OAuth提供程序在身份验证服务器上已禁用。
otp_disabled使用OTP（魔法链接、电子邮件OTP）登录已禁用。请检查服务器的配置。
otp_expired此登录的OTP代码已过期。请用户重新登录。
over_email_send_rate_limit已向此电子邮件地址发送过多电子邮件。请用户等待一段时间后再试。
over_request_rate_limit此客户端（IP地址）发送的请求过多。请用户几分钟后再试。有时这可能表明您的应用程序存在错误，错误地发送了过多请求（例如编写不当的useEffect React钩子）。
over_sms_send_rate_limit已向此电话号码发送过多短信。请用户等待一段时间后再试。
phone_exists电话号码已在系统中存在。
phone_not_confirmed由于电话号码未确认，不允许此用户登录。
phone_provider_disabled电话和密码注册已禁用。
provider_disabledOAuth提供程序已禁用。请检查服务器的配置。
provider_email_needs_verification并非所有OAuth提供程序都会验证其用户的电子邮件地址。Supabase身份验证要求验证电子邮件，因此在完成OAuth流程后发送验证电子邮件时会发出此错误。
reauthentication_needed用户需要重新进行身份验证才能更改密码。请用户通过调用supabase.auth.reauthenticate() API重新进行身份验证。
reauthentication_not_valid验证重新身份验证失败，代码不正确。请用户输入新代码。
refresh_token_not_found包含刷新令牌的会话未找到。
refresh_token_already_used刷新令牌已被撤销，且超出了刷新令牌重用间隔。有关更多信息，请参阅会话文档。
request_timeout处理请求花费的时间过长。请重试请求。
same_password更新密码的用户必须使用与当前使用的密码不同的密码。
saml_assertion_no_email登录后收到SAML断言（用户信息），但其中未找到必需的电子邮件地址。请检查提供程序的属性映射和/或配置。
saml_assertion_no_user_id登录后收到SAML断言（用户信息），但其中未找到必需的用户ID（称为NameID）。请检查SAML身份提供程序的配置。
saml_entity_id_mismatch（管理员API。）无法更新SAML身份提供程序的SAML元数据，因为更新中的实体ID与数据库中的实体ID不匹配。这相当于创建一个新的身份提供程序，您应该改为执行此操作。
saml_idp_already_exists（管理员API。）添加已添加的SAML身份提供程序。
saml_idp_not_found未找到SAML身份提供程序。最常见的情况是在使用未在Supabase身份验证中注册的SAML身份提供程序进行身份提供程序发起的登录后返回此错误。
saml_metadata_fetch_failed（管理员API。）添加或更新SAML提供程序失败，因为无法从提供的URL获取其元数据。
saml_provider_disabled在身份验证服务器上未启用使用SAML 2.0的企业单点登录。
saml_relay_state_expiredSAML中继状态是一个对象，用于跟踪supabase.auth.signInWithSSO()请求的进度。SAML身份提供程序应在固定时间后响应，之后会显示此错误。请用户重新登录。
saml_relay_state_not_foundSAML中继状态在过期后会逐步清理，这可能会导致此错误。请用户重新登录。
session_expired与API请求相关的会话已过期。如果配置了非活动超时，或者会话条目已超过配置的时间范围值，可能会发生这种情况。有关更多信息，请参阅会话文档。
session_not_found与API请求相关的会话不再存在。如果用户已注销，或者数据库中的会话条目以其他方式被删除，可能会发生这种情况。
signup_disabled服务器上已禁用注册（创建新账户）。
single_identity_not_deletable每个用户必须至少附加一个身份，因此如果某个身份是用户唯一的身份，则不允许删除（取消链接）该身份。
sms_send_failed发送短信失败。请检查您的短信提供程序配置。
sso_domain_already_exists（管理员API。）每个单点登录身份提供程序只能注册一个单点登录域。
sso_provider_not_found未找到单点登录提供程序。请检查supabase.auth.signInWithSSO()中的参数。
too_many_enrolled_mfa_factors用户只能注册固定数量的多因素身份验证因素。
unexpected_audience（已弃用的功能，无法通过Supabase客户端库使用。）请求的X-JWT-AUD声明与JWT的受众不匹配。
unexpected_failure身份验证服务出现故障或存在错误，但没有具体原因。
user_already_exists具有此信息（电子邮件地址、电话号码）的用户已存在，无法再次创建。
user_banned与API请求相关的用户具有仍然有效的banned_until属性。在清除此字段之前，不应尝试进一步的API请求。
user_not_found与API请求相关的用户不再存在。
user_sso_managed当用户来自单点登录时，用户的某些字段（如email）无法更新。
validation_failed提供的参数格式不符合预期。
weak_password用户注册或更改密码时未满足密码强度标准。使用AuthWeakPasswordError类可获取更多关于如何使密码通过验证的信息。

错误处理最佳实践

  • 始终使用 error.code 和 error.name 来识别错误，而非对错误消息进行字符串匹配。
  • 避免仅依赖 HTTP 状态码，因为它们可能会意外变更。