Document error responses and reserved names for section management APIs

jsinghmokha · claude · jsinghmokha · commit f6529e7db5fa · 2026-04-20T10:04:58.000-07:00
- Add error response tables to create, update, delete, add-item, and move-item APIs covering 400/403/404/409/412/428.
- Document the 409 Conflict "A section with this display name already exists." case and note that display name comparison is case-sensitive.
- Document the reserved system-defined section names (RecentChats, QuickViews, TeamsAndChannels, MutedChats, MeetingChats, EngageCommunities) in the teamworkSection resource and the create/update property tables.
- Fix the create-section request example to stop setting the read-only displayIcon.displayName property.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/api-reference/beta/api/teamworksection-delete.md b/api-reference/beta/api/teamworksection-delete.md
@@ -47,6 +47,15 @@ Don't supply a request body for this method.
 
 If successful, this method returns a `204 No Content` response code. It doesn't return anything in the response body.
 
+The following errors are possible.
+
+| Response code | Message |
+|:---|:---|
+| `403 Forbidden` | This section is system-generated and cannot be modified. System-defined sections can't be deleted. |
+| `404 Not Found` | The specified section was not found. |
+| `412 Precondition Failed` | The `If-Match` header value doesn't match the current section hierarchy version. [List sections](userteamwork-list-sections.md) again to retrieve the current **@microsoft.graph.sectionsVersion** annotation and retry. |
+| `428 Precondition Required` | The `If-Match` header is required for this operation. |
+
 ## Examples
 
 ### Request
diff --git a/api-reference/beta/api/teamworksection-post-items.md b/api-reference/beta/api/teamworksection-post-items.md
@@ -57,15 +57,19 @@ If successful, this method returns a `201 Created` response code and a [teamwork
 > [!NOTE]
 > The response includes an updated **@odata.etag** value. Use this value as the `If-Match` header for any subsequent mutation operations.
 
-This method can also return the following errors.
-
-| Scenario | HTTP code | Error code | Message |
-|:---------|:----------|:-----------|:--------|
-| Item already exists in this section | `409 Conflict` | `conflict` | This item is already in this section. |
-| Item already exists in another user-defined section | `409 Conflict` | `conflict` | This item is already associated with another section. Use the [move](teamworksectionitem-move.md) API to relocate it. |
-| Maximum items per section reached | `400 Bad Request` | `badRequest` | The maximum number of items in this section is reached. |
-| Invalid item ID | `400 Bad Request` | `badRequest` | The specified item ID isn't valid. Provide a valid chat, channel, meeting, or community ID. |
-| ETag version mismatch | `412 Precondition Failed` | `preconditionFailed` | The resource was modified after it was last read. Read the latest version and retry. |
+The following errors are possible.
+
+| Response code | Message |
+|:---|:---|
+| `400 Bad Request` | The 'id' property is required and must not be empty. |
+| `400 Bad Request` | The specified item ID is not valid. Provide a valid chat, channel, meeting, or community ID. |
+| `400 Bad Request` | The maximum number of items in this section has been reached. |
+| `403 Forbidden` | Access to this resource is denied. The caller must be a member of the conversation being added. |
+| `404 Not Found` | The specified section was not found. |
+| `409 Conflict` | This item is already in this section. |
+| `409 Conflict` | This item is already associated with another section. Use the [move](teamworksectionitem-move.md) API to relocate it. The response includes a `conflictingSectionId` detail with the ID of the section that currently holds the item. |
+| `412 Precondition Failed` | The `If-Match` header value doesn't match the current section hierarchy version. [List sections](userteamwork-list-sections.md) again to retrieve the current **@microsoft.graph.sectionsVersion** annotation and retry. |
+| `428 Precondition Required` | The `If-Match` header is required for this operation. |
 
 ## Examples
 
diff --git a/api-reference/beta/api/teamworksection-update.md b/api-reference/beta/api/teamworksection-update.md
@@ -47,7 +47,7 @@ In the request body, supply a JSON representation of only the properties to upda
 | Property | Type | Description |
 |:---------|:-----|:------------|
 | displayIcon | [sectionDisplayIcon](../resources/sectiondisplayicon.md) | The icon displayed for the section. |
-| displayName | String | The display name of the section. Maximum length is 50 characters. |
+| displayName | String | The display name of the section. Maximum length is 50 characters. Display names are case-sensitive and must be unique within a user's sections. The reserved system-defined names (`RecentChats`, `QuickViews`, `TeamsAndChannels`, `MutedChats`, `MeetingChats`, `EngageCommunities`) can't be used. |
 | isExpanded | Boolean | Indicates whether the section is expanded in the user interface. |
 | sortType | sectionSortType | The sort order of items in the section. The possible values are: `mostRecent`, `unreadThenMostRecent`, `nameAlphabetical`, `userDefinedCustomOrder`, `unknownFutureValue`. |
 
@@ -64,7 +64,19 @@ If successful, this method returns a `200 OK` response code and an updated [team
 > [!NOTE]
 > The response includes an updated **@odata.etag** value. Use this value as the `If-Match` header for any subsequent mutation operations.
 
-If the request specifies an unsupported **sortType** for the section type, this method returns a `400 Bad Request` response code. For more information, see the [Request body](#request-body) section.
+The following errors are possible.
+
+| Response code | Message |
+|:---|:---|
+| `400 Bad Request` | At least one property must be provided for update. |
+| `400 Bad Request` | The 'displayName' property must not be empty or whitespace, or must not exceed 50 characters. |
+| `400 Bad Request` | The property '{propertyName}' is read-only or not updatable. Only **displayName**, **displayIcon**, **isExpanded**, and **sortType** can be updated. |
+| `400 Bad Request` | The specified sort type is not valid for this section. For more information, see the [Request body](#request-body) section. |
+| `403 Forbidden` | This section is system-generated and cannot be modified. Only the **sortType** property can be updated on system-defined sections. |
+| `404 Not Found` | The specified section was not found. |
+| `409 Conflict` | A section with this display name already exists. Returned when the requested **displayName** matches an existing user-defined section or a reserved system-defined section name. The comparison is case-sensitive. |
+| `412 Precondition Failed` | The `If-Match` header value doesn't match the current section hierarchy version. [List sections](userteamwork-list-sections.md) again to retrieve the current **@microsoft.graph.sectionsVersion** annotation and retry. |
+| `428 Precondition Required` | The `If-Match` header is required for this operation. |
 
 ## Examples
 
diff --git a/api-reference/beta/api/teamworksectionitem-move.md b/api-reference/beta/api/teamworksectionitem-move.md
@@ -57,6 +57,17 @@ If successful, this action returns a `200 OK` response code and a [teamworkSecti
 > [!NOTE]
 > The response includes an updated **@odata.etag** value. Use this value as the `If-Match` header for any subsequent mutation operations.
 
+The following errors are possible.
+
+| Response code | Message |
+|:---|:---|
+| `400 Bad Request` | The 'targetSectionId' property is required and must not be empty. |
+| `400 Bad Request` | The source and target sections must be different. |
+| `403 Forbidden` | This section is system-generated and cannot be modified. Items can't be moved into or out of system-defined sections by using this action. |
+| `404 Not Found` | The specified section was not found, or the specified item was not found in this section. |
+| `412 Precondition Failed` | The `If-Match` header value doesn't match the current section hierarchy version. [List sections](userteamwork-list-sections.md) again to retrieve the current **@microsoft.graph.sectionsVersion** annotation and retry. |
+| `428 Precondition Required` | The `If-Match` header is required for this operation. |
+
 ## Examples
 
 ### Request
diff --git a/api-reference/beta/api/userteamwork-post-sections.md b/api-reference/beta/api/userteamwork-post-sections.md
@@ -49,7 +49,7 @@ The following table lists the properties that you can set when you create a **te
 | Property | Type | Description |
 |:---------|:-----|:------------|
 | displayIcon | [sectionDisplayIcon](../resources/sectiondisplayicon.md) | The icon displayed for the section. Optional. The **skinTone** property of the icon can't be set and is derived from user settings. |
-| displayName | String | The display name of the section. Required. Maximum length is 50 characters. |
+| displayName | String | The display name of the section. Required. Maximum length is 50 characters. Display names are case-sensitive and must be unique within a user's sections. The following names are reserved for system-defined sections and can't be used: `RecentChats`, `QuickViews`, `TeamsAndChannels`, `MutedChats`, `MeetingChats`, `EngageCommunities`. |
 | isExpanded | Boolean | Indicates whether the section is expanded in the user interface. Optional. The default value is `true`. |
 | sortType | sectionSortType | The sort order of items in the section. Optional. The default value is `userDefinedCustomOrder`. The valid values for user-defined sections are: `mostRecent`, `unreadThenMostRecent`, `userDefinedCustomOrder`, `unknownFutureValue`. The `nameAlphabetical` member isn't valid for user-defined sections. |
 
@@ -60,6 +60,20 @@ If successful, this method returns a `201 Created` response code and a [teamwork
 > [!NOTE]
 > The response includes an updated **@odata.etag** value. Use this value as the `If-Match` header for any subsequent mutation operations.
 
+The following errors are possible.
+
+| Response code | Message |
+|:---|:---|
+| `400 Bad Request` | The 'displayName' property is required and must not be empty. |
+| `400 Bad Request` | The 'displayName' property must not exceed 50 characters. |
+| `400 Bad Request` | The section display name contains invalid characters or format. |
+| `400 Bad Request` | The 'id', 'createdDateTime', 'lastModifiedDateTime', 'sectionType', or 'isHierarchicalViewEnabled' property is read-only and must not be provided when creating a section. |
+| `400 Bad Request` | The 'displayIcon.contentUrl' property is not supported, or the 'displayIcon.displayName' or 'displayIcon.skinTone' property is read-only and must not be provided. |
+| `400 Bad Request` | The maximum number of sections has been reached. |
+| `409 Conflict` | A section with this display name already exists. Returned when the requested **displayName** matches an existing user-defined section or one of the reserved system-defined section names (`RecentChats`, `QuickViews`, `TeamsAndChannels`, `MutedChats`, `MeetingChats`, `EngageCommunities`). The comparison is case-sensitive. |
+| `412 Precondition Failed` | The `If-Match` header value doesn't match the current section hierarchy version. [List sections](userteamwork-list-sections.md) again to retrieve the current **@microsoft.graph.sectionsVersion** annotation and retry. |
+| `428 Precondition Required` | The `If-Match` header is required for this operation. |
+
 ## Examples
 
 ### Request
@@ -79,8 +93,7 @@ If-Match: "1742515200"
 {
   "displayName": "Project Alpha",
   "displayIcon": {
-    "iconType": "🚀",
-    "displayName": "Rocket"
+    "iconType": "🚀"
   },
   "sortType": "mostRecent"
 }
diff --git a/api-reference/beta/resources/teamworksection.md b/api-reference/beta/resources/teamworksection.md
@@ -33,7 +33,7 @@ Represents a section in a user's Microsoft Teams chat list that organizes chats,
 |:---------|:-----|:------------|
 | createdDateTime | DateTimeOffset | Date and time when the section was created. Read-only. The timestamp type represents date and time information using ISO 8601 format and is always in UTC. For example, midnight UTC on Jan 1, 2024, is `2024-01-01T00:00:00Z`. |
 | displayIcon | [sectionDisplayIcon](sectiondisplayicon.md) | The icon displayed for the section. |
-| displayName | String | The display name of the section. Required. Maximum length is 50 characters. |
+| displayName | String | The display name of the section. Required. Maximum length is 50 characters. Display names are case-sensitive and must be unique within a user's sections. The following names are reserved for system-defined sections and can't be used when creating a user-defined section: `RecentChats`, `QuickViews`, `TeamsAndChannels`, `MutedChats`, `MeetingChats`, `EngageCommunities`. |
 | id | String | The unique identifier for the section. Read-only. |
 | isExpanded | Boolean | Indicates whether the section is expanded in the user interface. The default value is `true`. |
 | isHierarchicalViewEnabled | Boolean | Indicates whether the hierarchical view is enabled for the section. Read-only. |
@@ -49,6 +49,21 @@ Represents a section in a user's Microsoft Teams chat list that organizes chats,
 | systemDefined | A section managed by the service that can't be deleted. Only the **sortType** property can be updated. |
 | unknownFutureValue | Evolvable enumeration sentinel value. Don't use. |
 
+#### System-defined sections
+
+System-defined sections are provisioned by the service and appear in every user's section list. Their **displayName** values are reserved and can't be used for user-defined sections.
+
+| displayName | Description |
+|:------------|:------------|
+| RecentChats | The default chats section. |
+| QuickViews | The Quick views section. |
+| TeamsAndChannels | The teams and channels section. |
+| MutedChats | The muted chats section. |
+| MeetingChats | The meeting chats section. |
+| EngageCommunities | The communities section. |
+
+System-defined sections can't be deleted, and only the **sortType** property can be updated. Attempts to update other properties or to delete a system-defined section return `403 Forbidden`. Listing [items](teamworksectionitem.md) on a system-defined section is not supported and returns `400 Bad Request`.
+
 ### sectionSortType values
 
 | Member | Description |
