常见的 Google Classroom API 错误消息

本页介绍了以下类型的 Google Classroom API 常见错误消息、问题和可能的操作:

HTTP 400:FAILED_PRECONDITION

如果用户尝试执行无法被允许的操作(可能是由于用户达到了限制或应用处于某种状态,例如 CourseNotModifiable),系统会返回 FAILED_PRECONDITION。如需修复 FAILED_PRECONDITION,请指示用户执行某些操作,然后重试。或者,在某些情况下,您可以使用其他端点代表用户修正状态。

AttachmentNotVisible

AttachmentNotVisible 表示指定的一个或多个附件对用户不可见、不是请求的类型,或者不存在。例如,未与用户共享的云端硬盘内容会返回此错误。

可能的措施:说明失败的原因,并建议用户重新检查他们添加的标识符(例如云端硬盘文件 ID)。此外,请确保用户拥有查看附件的适当权限。

CannotRemoveCourseFolderOwner

CannotRemoveCourseFolderOwner 表示无法移除课程 Google 云端硬盘文件夹的所有者。

可能的措施:说明失败的原因,并建议用户将课程云端硬盘文件夹的所有权转移给其他用户,然后重试。

CannotRemoveCourseOwner

CannotRemoveCourseOwner 表示无法移除课程所有者。

可能的措施:说明失败的原因,并建议不要移除课程所有者。在大多数情况下,用户会尝试移除自己,但系统不允许这样做。

CannotRemoveCourseOwnerTransferIncomplete

CannotRemoveCourseOwnerTransferIncomplete 表示由于此课程的所有权转移仍在进行中,因此无法移除课程所有者。

可能的操作:说明失败的原因,并建议用户等待几分钟,以便转移课程所有权的异步操作完成,然后重试。

CannotRemoveTeacherWithNoCourseOwner

CannotRemoveTeacherWithNoCourseOwner 表示无法从没有所有者的课程中移除教师。

可能的措施:说明失败的原因,并建议不要移除教师。在大多数情况下,课程所有者的用户账号被删除,导致课程状态无效。

CourseMemberLimitReached

CourseMemberLimitReached 表示尝试执行的操作会导致课程成员数量超出允许的上限。此代码通常由 students.create() 返回。如需了解详情,请参阅邀请学生加入课程帮助中心文章中的“课程人数限制”部分。

可能的措施:说明失败的原因,并建议用户移除不必要的课程成员

CourseNotModifiable

CourseNotModifiable 表示相关课程处于不允许修改其属性(除了课程状态本身)的状态。

可能的措施:提示用户将课程更改为可修改的课程状态。如需更改状态,请使用 courses.patch()。您可以在更改其他属性的请求中更改课程状态。

CourseTeacherLimitReached

CourseTeacherLimitReached 表示所请求的操作会导致课程教师数量超出允许的上限。此代码通常由 teachers.create() 返回。如需了解详情,请参阅在课程中添加助理教师这篇帮助中心文章的“课程人数限制”部分。

可能的措施:说明失败的原因,并建议用户移除不必要的课程教师。如果适用于您的应用,您可以使用 teachers.delete() 代表用户管理教师名单。

InactiveCourseOwner

InactiveCourseOwner 表示由于课程所有者的账号已被删除,因此不允许执行请求的操作。课程所有者的管理员需要先恢复课程所有者的账号,然后才能执行所请求的操作。

可能的措施:说明失败原因,并建议管理员先恢复课程所有者的账号,然后重试操作。

IneligibleOwner

IneligibleOwner 表示由于用户不是助教,因此无法将其添加为课程所有者。

可能的措施:说明失败的原因。如果请求的用户不是管理员,请建议他们先向用户发送加入课程教师团队的邀请,然后再更新所有者。如果请求添加的用户是管理员,请建议他们先将该用户添加为课程的辅导教师。

PendingInvitationExists

PendingInvitationExists 表示有人已受邀接管课程。如果课程所有权转移期间之前已发起转移,但新所有者尚未接受,则会出现此错误。

UserCannotOwnCourse

UserCannotOwnCourse 表示无法将用户添加为课程所有者。

可能的措施:说明失败的原因,并建议将用户设为课程所有者时无法创建课程。如果非管理员请求者尝试创建课程,并将自己以外的用户设为所有者,则可能会看到此错误。如果指定为所有者的用户账号不存在或用户不在其网域中,请求用户访问权限的管理员可能会看到此错误。

UserGroupsMembershipLimitReached

UserGroupsMembershipLimitReached 表示用户已加入允许的群组数量上限,无法加入任何课程。此代码通常由 students.create()teachers.create() 返回。如需了解详情,请参阅邀请学生加入课程帮助中心文章的“课程人数限制”部分。

可能的措施:说明失败的原因,并建议用户退出所有未参与的课程。如果用户需要参加更多课程,可以考虑创建其他账号。如果适用于您的应用,您可以使用 students.create()teachers.delete() 代表用户管理名单。

HTTP 403:PERMISSION_DENIED

如果最终用户不符合访问的前提条件,所有 Google 课堂 API 方法都可能会返回 PERMISSION_DENIED (HTTP 403) 错误。随错误一起显示的消息包含错误消息,可帮助您找出原因并引导用户采取适当的措施。

以下部分介绍了常见的 Google 课堂 API 错误消息。

CannotDirectAddUser

CannotDirectAddUser 表示无法直接将用户添加到课程。如果网域管理员尝试将用户添加到课程,但该用户没有电子邮件地址或不属于该网域,就会出现此错误代码。

可能的措施:说明失败原因,并建议域名管理员检查用户账号是否存在且是否位于课程管理员的网域中。

ClassroomApiDisabled

ClassroomApiDisabled 表示发出请求的用户无权访问 Classroom API。

可能的措施:引导用户参阅有关启用 Google 课堂数据访问权限的说明。另请参阅 ClassroomDisabled,因为用户可能使用的是错误的账号。

ClassroomDisabled

ClassroomDisabled 表示发出请求的用户无权访问 Google 课堂。

可能的措施:引导用户参阅有关启用 Google 课堂访问权限的说明。用户可能也使用了错误的账号,因此您还可以提供使用多个账号的链接,以便用户选择正确的账号。

ExpiredAddOnToken

ExpiredAddOnToken 表示用于调用 API 的插件令牌已过期。

可能的措施:提示用户刷新页面或重新登录该插件,以便您从请求网址中获取新的 addOnToken 查询参数

InvalidAddOnToken

InvalidAddOnToken 表示请求中传递的插件令牌无权在作业中创建插件附件。

可能的措施:如果用户使用与 Google 课堂中账号不同的账号登录插件,则可能会抛出此错误。请指示用户退出浏览器中的所有其他账号,或在 Chrome 无痕式窗口中打开 Google 课堂。

ProjectPermissionDenied

ProjectPermissionDenied 表示请求尝试修改与其他 Play 管理中心项目关联的资源。

可能的措施:表明您的应用无法发出预期的请求。只有创建资源的 OAuth 客户端 ID 的 Play 管理中心项目才能执行此操作。

UserIneligibleToUpdateGradingPeriodSettings

UserIneligibleToUpdateGradingPeriodSettings 表示请求尝试修改某门课程的评分周期设置,但请求用户或课程所有者没有适当的 Google Workspace 教育版许可。

可能的措施:指明由于请求用户或课程所有者的许可状态,您的应用无法发出更新评分周期设置的预期请求。您可以在 Google 管理控制台中分配许可。

HTTP 429:RESOURCE_EXHAUSTED

如果由于某些资源(例如配额或服务器容量)已耗尽而无法执行请求的操作,系统会返回 RESOURCE_EXHAUSTED。这类请求错误通常是由于应用产生了过载所致。

为避免触发这些限制并提高应用的可靠性,请使用重试机制。有效的重试机制包括:

  • 使用截断指数退避算法重试请求,并最大限度地提高并发环境中的请求吞吐量。

  • 为避免冲突,请考虑使用带抖动的截断指数退避算法。引入抖动可以引入随机延迟,从而分散请求中的峰值,从而帮助您的请求更快地成功。

如果您的应用因配额限制而返回 RESOURCE_EXHAUSTED 错误,请提交配额增加申请。如需了解详情,请参阅 Monitor API 配额帮助中心文章。

UserCourseJoinRateLimitReached

UserCourseJoinRateLimitReached 表示用户当天加入的课程数量已达到上限。如需了解详情,请参阅了解群组的政策和限制帮助中心文章中的“群组邀请和群组人数”部分。

可能的措施:说明失败的原因,并建议用户等待一天后再加入课程。

HTTP 500:INTERNAL

INTERNAL 表示在处理请求时出现意外错误。通常,您还可以使用指数退避算法重试请求来解决 INTERNAL 请求错误。如果 INTERNAL 错误仍然存在,您可以通过在 Classroom API 公开问题跟踪器中提交 bug 来报告该错误。