本页面介绍了以下类型的错误的一些常见 Google Classroom API 错误消息、问题和可能的措施:
- HTTP 400:
FAILED_PRECONDITION
- HTTP 403:
PERMISSION_DENIED
- HTTP 429:
RESOURCE_EXHAUSTED
- HTTP 500:
INTERNAL
HTTP 400:FAILED_PRECONDITION
当用户尝试执行不允许的操作时,系统会返回 FAILED_PRECONDITION
,原因可能是用户已达到限制或应用状态(例如 CourseNotModifiable
)。如需修复 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()
方法代表用户管理教师名单。
CourseTitleCannotContainUrl
CourseTitleCannotContainUrl
表示不允许执行所请求的操作,因为该操作会在课程标题中引入网址。课程标题不支持网址格式。
可能的操作:说明失败的原因,并建议用户从 title
字段中移除相应网址模式。description
字段中允许使用网址。
CourseTopicLimitReached
CourseTopicLimitReached
表示所请求的操作会超出课程中允许的最大主题数。此代码通常由 courses.topics.create()
方法返回。
可能的操作:
说明失败的原因,并建议用户移除不必要的主题。如果您的应用适用,您可以使用 courses.topics.delete()
方法代表用户管理主题。
EmptyAssignees
EmptyAssignees
表示所请求的操作会从相应作业中移除所有分配对象。不支持没有分配对象的作业。
可能的操作:说明失败原因,并建议课程所有者无法移除所有受让人。
InactiveCourseOwner
InactiveCourseOwner
表示由于课程所有者的账号已被删除,因此不允许执行所请求的操作。课程所有者的管理员需要先恢复课程所有者的账号,然后才能执行所请求的操作。
可能的操作: 说明失败原因,并建议管理员在重试操作之前恢复课程所有者的账号。
IneligibleOwner
IneligibleOwner
表示相应用户无法添加为课程的所有者,因为该用户不是共同教师。
可能采取的行动: 描述失败的原因。如果请求用户不是管理员,请建议他们先向该用户发送课程教师邀请,然后再更新所有者。如果请求用户是管理员,建议他们先将该用户添加为课程的辅讲教师。
PendingInvitationExists
PendingInvitationExists
表示已邀请某人成为课程的所有者。此错误发生在课程所有权转移期间,原因是之前已开始转移,但新所有者尚未接受。
UserCannotOwnCourse
UserCannotOwnCourse
表示无法将相应用户添加为课程的所有者。
可能的操作:描述失败的原因,并建议不要将用户设为课程所有者来创建课程。如果非管理员请求用户尝试创建课程,但将自己以外的用户设为所有者,则可能会看到此错误。如果指定为所有者的用户账号不存在或用户不在管理员的网域中,请求用户可能会看到此错误。
UserGroupsMembershipLimitReached
UserGroupsMembershipLimitReached
表示用户已加入允许加入的群组数量上限,无法再加入任何课程。此代码通常由 students.create()
或 teachers.create()
返回。如需了解详情,请参阅邀请学生加入课程帮助中心文章的“课程人数限制”部分。
可能的操作:说明失败的原因,并建议用户退出未参与的任何课程。如果用户需要参加更多课程,可以考虑创建其他账号。如果您的应用适用,您可以使用 students.create()
或 teachers.delete()
代表用户管理名单。
HTTP 403:PERMISSION_DENIED
如果最终用户不满足访问前提条件,所有 Classroom API 方法都可能会返回 PERMISSION_DENIED
(HTTP 403) 错误。错误随附的消息包含错误消息,可帮助您确定原因并引导用户采取适当的措施。
以下部分介绍了常见的 Classroom API 错误消息。
CannotDirectAddUser
CannotDirectAddUser
表示无法直接将用户添加到课程中。当网域管理员尝试向课程添加用户,但该用户没有电子邮件地址或不属于该网域时,系统会显示此代码。
可能的操作:说明失败的原因,并建议网域管理员检查用户账号是否存在以及是否位于课程管理员的网域中。
ClassroomApiDisabled
ClassroomApiDisabled
表示发出请求的用户无权访问 Classroom API。
可能的操作: 引导用户按照说明启用 Google 课堂数据访问权限。 另请参阅 ClassroomDisabled,因为用户可能使用了错误的账号。
ClassroomDisabled
ClassroomDisabled
表示请求用户无权访问 Google 课堂。
可能的操作: 引导用户参阅有关启用 Google 课堂访问权限的说明。 用户可能还使用了错误的账号,因此您还可以提供指向使用多个账号的链接,以便用户选择正确的账号。
ExpiredAddOnToken
ExpiredAddOnToken
表示用于调用 API 的插件令牌已过期。
可能的措施:提示用户刷新页面或重新登录到插件,以便您可以从请求网址中获取新的 addOnToken
查询参数。
InvalidAddOnToken
InvalidAddOnToken
表示请求中传递的插件令牌未获授权在作业中创建插件附件。
可能的操作:如果用户使用与 Google 课堂中的账号不同的账号登录插件,则可能会抛出此错误。指示用户退出浏览器中的所有其他账号,或在 Chrome 无痕窗口中打开 Google 课堂。
ProjectPermissionDenied
ProjectPermissionDenied
表示请求尝试修改与另一个开发者控制台项目关联的资源。
可能的操作:表明您的应用无法发出预期请求。只能由创建相应资源的 OAuth 客户端 ID 的开发者控制台项目发出。
UserIneligibleToUpdateGradingPeriodSettings
UserIneligibleToUpdateGradingPeriodSettings
表示相应请求尝试修改课程中的学期设置,但请求用户或课程所有者没有相应的 Google Workspace 教育版许可,或者请求用户不是课程教师或网域管理员。
可能的操作:指明您的应用因许可或课程角色状态而无法发出更新评分周期设置的预期请求。您可以在 Google 管理控制台中分配许可。
HTTP 429:RESOURCE_EXHAUSTED
当由于配额或服务器容量等资源耗尽而导致请求的操作不被允许时,系统会返回 RESOURCE_EXHAUSTED
。此类请求错误通常是因为您的应用产生了过大的负载。
为避免触发这些限制并提高应用的可靠性,请使用重试机制。有效的重试机制包括:
使用截断指数退避算法重试请求,并最大限度地提高并发环境中的请求吞吐量。
为避免冲突,请考虑使用带抖动的截断指数退避算法。引入抖动可以引入随机延迟,从而分散请求峰值,有助于更快地成功发送请求。
如果您的应用因配额限制而返回 RESOURCE_EXHAUSTED
错误,请提交配额增加申请。如需了解详情,请参阅监控 API 配额帮助中心文章。
UserCourseJoinRateLimitReached
UserCourseJoinRateLimitReached
表示用户在一天内加入的课程数量已达到上限。如需了解详情,请参阅了解群组政策和限制帮助中心文章的“群组邀请和规模”部分。
可能的操作:说明失败原因,并建议用户等待一天后再加入课程。
HTTP 500:INTERNAL
INTERNAL
表示在处理请求时出现意外错误。INTERNAL
请求错误通常也可以通过使用指数退避算法重试请求来解决。如果 INTERNAL
错误仍然存在,您可以在 Classroom API 公开问题跟踪器上报告此 bug。