Request Errors

要求錯誤

Classroom API 錯誤可能會包含錯誤代碼,協助您找出原因並妥善處理錯誤。視代碼而定,您可以重試要求,或引導使用者採取特定動作。

本頁詳細說明可能的錯誤代碼,並依 HTTP 代碼分組。如要進一步瞭解錯誤訊息的結構,請參閱「錯誤訊息結構」。

本頁詳細說明可能的錯誤代碼,並依 HTTP 代碼分組。請參閱參考文件,瞭解哪些方法會傳回特定錯誤代碼。

HTTP 400:FAILED_PRECONDITION

如果使用者嘗試執行無法允許的動作,例如因為使用者已達到限制或應用程式狀態 (例如 CourseNotModifiable),系統就會傳回 FAILED_PRECONDITION。如要修正 FAILED_PRECONDITION,請指示使用者採取某些動作,然後重試。在某些情況下,您可以使用其他端點,代表使用者修正狀態。

PendingInvitationExists

PendingInvitationExists 表示已邀請他人擔任課程擁有者。在轉移課程擁有權時,如果先前已開始轉移,但新擁有者尚未接受,就會發生這個錯誤。

CourseMemberLimitReached

CourseMemberLimitReached 表示嘗試的動作會超過課程成員人數上限。這個代碼通常會由 students.create() 傳回。如需更多資訊,請參閱「邀請學生加入課程」說明中心文章中的「課程人數限制」一節。

可能的動作:說明失敗的原因,並建議使用者移除不必要的課程成員

CourseNotModifiable

CourseNotModifiable 表示相關課程處於不允許修改屬性 (除了課程狀態本身) 的狀態。

可能的動作:提示使用者將課程變更為可修改的課程狀態。如要變更狀態,請使用 courses.patch()。您可以在變更其他屬性的要求中變更課程狀態。

CourseTeacherLimitReached

CourseTeacherLimitReached 表示要求的動作會超過允許的課程老師人數上限。這個代碼通常會由 teachers.create() 方法傳回。詳情請參閱為課程新增共同授課老師說明中心文章中的「課程人數限制」一節。

可能的動作:說明失敗的原因,並建議使用者移除不必要的課程教師。如果適用於您的應用程式,您可以使用 teachers.delete() 方法,代表使用者管理教師名單。

CourseTopicLimitReached

CourseTopicLimitReached 表示要求的動作會超過課程允許的主題數量上限。這個代碼通常會由 courses.topics.create() 方法傳回。

可能的動作:說明失敗原因,並建議使用者移除不必要的主題。如果您的應用程式適用,您可以使用 courses.topics.delete() 方法,代表使用者管理主題。

UserGroupsMembershipLimitReached

UserGroupsMembershipLimitReached 表示使用者已加入允許的群組數量上限,因此無法加入任何課程。這個代碼通常會由 students.create()teachers.create() 傳回。詳情請參閱「邀請學生加入課程」說明中心文章中的「課程人數限制」一節。

可能的行動:說明失敗的原因,並建議使用者離開未參與的課程。如果使用者需要參與更多課程,可以考慮建立其他帳戶。如果適用於您的應用程式,您可以使用 students.create()teachers.delete() 代表使用者管理名單。

AttachmentNotVisible

AttachmentNotVisible 表示指定的一或多個附件不是使用者可見,不是所要求的類型,或是不存在。舉例來說,如果雲端硬碟項目尚未與使用者共用,就會傳回這項錯誤。

可能的動作:說明失敗的原因,並建議使用者重新檢查已加入的 ID (例如雲端硬碟檔案 ID)。此外,請確認使用者具備查看附件的適當權限。

CannotRemoveCourseFolderOwner

CannotRemoveCourseFolderOwner 表示課程雲端硬碟資料夾的擁有者可能無法移除。

可能的行動:說明失敗的原因,並建議使用者將課程雲端硬碟資料夾的擁有權轉移給其他使用者,然後再試一次。

CannotRemoveCourseOwner

CannotRemoveCourseOwner 表示課程擁有者可能無法移除。

可能的動作:說明失敗的原因,並建議不要移除課程擁有者。在大多數情況下,使用者會嘗試移除自己,但這項操作是不允許的。

CannotRemoveCourseOwnerTransferIncomplete

CannotRemoveCourseOwnerTransferIncomplete 表示課程擁有權轉移作業仍在進行中,因此無法移除課程擁有者。

可能的動作:說明失敗的原因,並建議使用者稍待片刻,讓轉移課程擁有權的非同步動作完成,然後再試一次。

CannotRemoveTeacherWithNoCourseOwner

CannotRemoveTeacherWithNoCourseOwner 表示無法從沒有擁有者的課程中移除老師。

可能的動作:說明失敗的原因,並建議不要移除老師。在大多數情況下,課程擁有者的使用者帳戶遭到刪除,導致課程狀態無效。

InactiveCourseOwner

InactiveCourseOwner 表示課程擁有者的帳戶已刪除,因此無法執行要求的動作。課程擁有者的管理員必須先還原課程擁有者的帳戶,才能採取要求的行動。

可能的動作:說明失敗的原因,並建議管理員在重試作業前還原課程擁有者的帳戶

IneligibleOwner

IneligibleOwner 表示使用者不是共同教師,因此無法新增為課程擁有者。

可能的行動:說明失敗的原因。如果提出要求的使用者不是管理員,建議他們先邀請使用者擔任課程老師,再更新擁有者。如果要求的使用者是管理員,請建議他們先將使用者新增為課程的共同授課者。

UserCannotOwnCourse

UserCannotOwnCourse 表示無法將使用者新增為課程擁有者。

可能的行動:說明失敗的原因,並建議使用者不要建立課程。如果非管理員要求使用者嘗試建立課程,並將自己以外的使用者設為課程擁有者,就可能會看到這則錯誤訊息。如果管理員要求的使用者指定的使用者帳戶不存在,或是使用者不在自己的網域中,使用者可能會看到這項錯誤。

HTTP 429:RESOURCE_EXHAUSTED

如果系統因某些資源 (例如配額或伺服器容量) 用盡,而無法允許要求的動作,就會傳回 RESOURCE_EXHAUSTED。這類要求錯誤通常是因為應用程式產生過多負載。

如要避免觸發這些限制並提高應用程式的可靠性,請使用重試機制。有效的重試機制包括:

  • 使用部分指數輪詢重試要求,並在並行環境中盡可能提高要求的總處理量。

  • 為避免衝突,建議您使用帶有抖動的片段指數輪詢。導入雜訊可讓要求成功的速度加快,因為這項功能會導入隨機延遲,將要求的尖峰分散開來。

如果應用程式因配額限制而傳回 RESOURCE_EXHAUSTED 錯誤,請提交配額調高申請。詳情請參閱「Monitor API 配額」說明中心文章。

UserCourseJoinRateLimitReached

UserCourseJoinRateLimitReached 表示使用者已加入一天內允許的課程數量上限。詳情請參閱「瞭解網路論壇政策與使用限制」說明中心文章中的「網路論壇邀請與人數」一節。

可能的動作:說明失敗原因,並建議使用者等待一天再加入課程。

HTTP 500:INTERNAL

INTERNAL 表示處理要求時發生非預期的錯誤。您也可以使用指數輪詢重試要求,通常也能解決 INTERNAL 要求錯誤。如果 INTERNAL 錯誤持續發生,請前往 Classroom API 公開 Issue Tracker 回報錯誤。