处理 Firebase Apple 平台身份验证错误

如果身份验证方法中的完成回调函数收到的 NSError 参数不是 nil,则表示出现了错误。如需在您的正式版代码中分派适当的错误处理逻辑,请查看下文中列出的通用错误代码和与特定方法相关的错误代码。

一些错误可以通过特定用户操作解决。例如,用户重新登录即可解决 FIRAuthErrorCodeUserTokenExpired 错误,用户提供正确密码即可解决 FIRAuthErrorCodeWrongPassword 错误。

除了 FIRAuthErrorCodeNetworkErrorFIRAuthErrorCodeTooManyRequests 外,使用同样的参数重新尝试失败的操作无论如何都不会成功。请勿对操作在服务器端是否生效进行任何假设。

在调查或记录错误时,可以查阅 userInfo 字典。FIRAuthErrorNameKey 包含一个跨平台错误名称字符串,可用于识别错误。NSLocalizedDescriptionKey 则包含错误描述。此描述专门面向开发者,不适用于用户。NSUnderlyingErrorKey 包含引起相关错误的底层错误(如果存在底层错误)。

除上文列出的主要字段以外,您还可以在 userInfo 字典中找到有助于诊断错误的其他字段。

所有 API 方法通用的错误代码

代码 含义
FIRAuthErrorCodeNetworkError 表示操作过程中发生了网络错误。
FIRAuthErrorCodeUserNotFound 表示未找到用户帐号。如果用户帐号已删除,就可能会出现这个错误。
FIRAuthErrorCodeUserTokenExpired 表示当前用户的令牌已过期。例如,用户可能在其他设备上更改了帐号密码。您必须提示用户在此设备上重新登录。
FIRAuthErrorCodeTooManyRequests 表示之前从调用方设备向 Firebase 身份验证服务器发出的请求数量异常,因此该请求已被阻止。请过一段时间再试。
FIRAuthErrorCodeInvalidAPIKey 表示该应用配置了无效的 API 密钥。
FIRAuthErrorCodeAppNotAuthorized 表示该应用无权利用所提供的 API 密钥来使用 Firebase Authentication。请转到 Google API 控制台,在凭据标签页下检查您正在使用的 API 密钥是否将您应用的软件包 ID 列入了白名单。
FIRAuthErrorCodeKeychainError 表示访问密钥链时出错。NSError.userInfo 字典中的 NSLocalizedFailureReasonErrorKeyNSUnderlyingErrorKey 字段包含了关于出现的错误的详细信息。
FIRAuthErrorCodeInternalError 表示发生了内部错误。请在报告错误时提供完整的 NSError 对象。

与特定方法相关的错误代码

FIRAuth

fetchProvidersForEmail:completion:

代码 含义
FIRAuthErrorCodeInvalidEmail 表示电子邮件地址格式错误。

signInWithEmail:password:completion:

代码 含义
FIRAuthErrorCodeOperationNotAllowed 表示电子邮件和密码帐号未启用。请在 Firebase 控制台的“Auth”部分将其启用。
FIRAuthErrorCodeInvalidEmail 表示电子邮件地址格式错误。
FIRAuthErrorCodeUserDisabled 表示该用户帐号已停用。
FIRAuthErrorCodeWrongPassword 表示用户尝试使用错误的密码登录。

signInWithCredential:completion:

代码 含义
FIRAuthErrorCodeInvalidCredential 表示提供的凭据无效。如果凭据已过期或格式错误,就可能会出现这个错误。
FIRAuthErrorCodeInvalidEmail 如果凭据的类型为 EmailPasswordAuthCredential,则表示电子邮件地址格式错误。
FIRAuthErrorCodeOperationNotAllowed 表示该凭据代表的身份提供方帐号未启用。请在 Firebase 控制台的“Auth”部分将其启用。
FIRAuthErrorCodeEmailAlreadyInUse 表示该凭据声明的电子邮件地址(例如,Facebook 访问令牌中的电子邮件地址)已被现有帐号使用,无法使用此登录方法进行身份验证。为此用户的电子邮件调用 fetchProvidersForEmail,提示该用户使用返回的任一登录提供方帐号登录。只有在 Firebase 控制台的“Authentication”(身份验证)设置下启用了“每个电子邮件地址一个帐号”设置时才会出现这个错误。
FIRAuthErrorCodeUserDisabled 表示该用户帐号已停用。
FIRAuthErrorCodeWrongPassword 如果凭据的类型为 EmailPasswordAuthCredential,则表示用户尝试使用错误的密码登录。

signInAnonymouslyWithCompletion:

代码 含义
FIRAuthErrorCodeOperationNotAllowed 表示未启用匿名帐号。请在 Firebase 控制台的“Auth”部分将其启用。

signInWithCustomToken:completion:

代码 含义
FIRAuthErrorCodeInvalidCustomToken 表示自定义令牌发生了验证错误。
FIRAuthErrorCodeCustomTokenMismatch 表示服务帐号和 API 密钥分属不同的项目。

createUserWithEmail:password:completion:

代码 含义
FIRAuthErrorCodeInvalidEmail 表示电子邮件地址格式错误。
FIRAuthErrorCodeEmailAlreadyInUse 表示用于尝试注册的电子邮件已经存在。调用 fetchProvidersForEmail 检查该用户曾用过的登录机制,提示用户使用其中一种进行登录。
FIRAuthErrorCodeOperationNotAllowed 表示电子邮件和密码帐号未启用。请在 Firebase 控制台的“Authentication”(身份验证)部分将其启用。
FIRAuthErrorCodeWeakPassword 表示尝试设置的密码强度太弱。NSError.userInfo 字典对象中的 NSLocalizedFailureReasonErrorKey 字段包含更详细的说明,可供用户查看。

signOut:

代码 含义
FIRAuthErrorCodeKeychainError 表示访问密钥链时出错。NSError.userInfo 字典中的 NSLocalizedFailureReasonErrorKeyNSUnderlyingErrorKey 字段包含了关于出现的错误的详细信息。

FIRUser

FIRUser 操作常见错误

代码 含义
FIRAuthErrorCodeInvalidUserToken 表示该已登录用户的刷新令牌(含会话信息)无效。您必须提示用户在此设备上重新登录。
FIRAuthErrorCodeUserDisabled 表示该用户的帐号已停用,只有在 Firebase 控制台的“用户”面板中重新启用后方可继续使用。

reauthenticateWithCredential:completion:

代码 含义
FIRAuthErrorCodeInvalidCredential 表示提供的凭据无效。如果凭据已过期或格式错误,就可能会出现这个错误。
FIRAuthErrorCodeInvalidEmail 如果凭据的类型为 EmailPasswordAuthCredential,则表示电子邮件地址格式错误。
FIRAuthErrorCodeWrongPassword 如果凭据的类型为 EmailPasswordAuthCredential,则表示用户尝试使用错误的密码重新进行验证。
FIRAuthErrorCodeUserMismatch 表示尝试重新进行身份验证的用户不是当前用户。
FIRAuthErrorCodeOperationNotAllowed 表示该凭据代表的身份提供方帐号未启用。请在 Firebase 控制台的“Auth”部分将其启用。
FIRAuthErrorCodeEmailAlreadyInUse 表示该凭据声明的电子邮件地址(例如,Facebook 访问令牌中的电子邮件地址)已被现有帐号使用,无法使用此登录方法重新进行身份验证。为此用户的电子邮件调用 fetchProvidersForEmail,提示该用户使用返回的任一登录提供方帐号登录。只有在 Firebase 控制台的“Authentication”(身份验证)设置下启用了“每个电子邮件地址一个帐号”设置时才会出现这个错误。
FIRAuthErrorCodeUserDisabled 表示该用户帐号已停用。

updateEmail:completion:

代码 含义
FIRAuthErrorCodeEmailAlreadyInUse 表示电子邮件已被其他帐号使用。
FIRAuthErrorCodeInvalidEmail 表示电子邮件地址格式错误。
FIRAuthErrorCodeRequiresRecentLogin 更新用户的电子邮件是一项涉及安全的操作,用户必须在近期内登录过才能执行。此错误表示该用户近期内未进行登录。如需解决这个问题,可以调用 FIRUser 中的 reauthenticateWithCredential:completion: 重新对用户进行身份验证。

updatePassword:completion:

代码 含义
FIRAuthErrorCodeOperationNotAllowed 表示管理员已停用使用指定的身份提供方登录。
FIRAuthErrorCodeRequiresRecentLogin 更新用户的密码是一项涉及安全的操作,用户必须在近期内登录过才能执行。此错误表示该用户近期内未进行登录。如需解决这个问题,可以调用 FIRUser 中的 reauthenticateWithCredential:completion: 重新对用户进行身份验证。
FIRAuthErrorCodeWeakPassword 表示尝试设置的密码强度太弱。NSError.userInfo 字典对象中的 NSLocalizedFailureReasonErrorKey 字段包含更详细的说明,可供用户查看。

linkWithCredential:completion:

代码 含义
FIRAuthErrorCodeProviderAlreadyLinked 表示尝试对已与此帐号关联的某一类型的提供方进行关联。
FIRAuthErrorCodeCredentialAlreadyInUse 表示尝试对已与其他 Firebase 帐号关联的凭据进行关联。
FIRAuthErrorCodeOperationNotAllowed 表示该凭据代表的身份提供方帐号未启用。请在 Firebase 控制台的“Auth”部分将其启用。

此方法可能还会返回与 FIRUser 上的 updateEmail:completion:updatePassword:completion: 有关的错误代码。

unlinkFromProvider:completion:

代码 含义
FIRAuthErrorCodeNoSuchProvider 表示尝试对未与此帐号关联的某一提供方取消关联。
FIRAuthErrorCodeRequiresRecentLogin 更新电子邮件是一项涉及安全的操作,用户必须在近期内登录过才能执行。此错误表示该用户近期内未进行登录。如需解决这个问题,可以调用 FIRUser 中的 reauthenticateWithCredential:completion: 重新对用户进行身份验证。

sendEmailVerificationWithCompletion:

代码 含义
FIRAuthErrorCodeUserNotFound 表示未找到用户帐号。

deleteWithCompletion:

代码 含义
FIRAuthErrorCodeRequiresRecentLogin 删除用户帐号是一项涉及安全的操作,用户必须在近期内登录过才能执行。此错误表示该用户近期内未进行登录。如需解决这个问题,可以调用 FIRUser 中的 reauthenticateWithCredential:completion: 重新对用户进行身份验证。