Skip to content

Add error responses to ML Delete API documentation #11957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kolchfa-aws wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add error responses to ML Delete API documentation #11957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bca6508
Add error responses to ML Delete API documentation
kolchfa-aws Feb 25, 2026
576b13f
Add error response to delete context management
kolchfa-aws Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions _ml-commons-plugin/api/agent-apis/delete-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,24 @@ DELETE /_plugins/_ml/agents/MzcIJX8BA7mbufL6DOwl
"_seq_no" : 27,
"_primary_term" : 18
}
```

## Error responses

If you attempt to delete an agent that doesn't exist, OpenSearch returns a 404 Not Found error:

```json
{
"error": {
"root_cause": [
{
"type": "status_exception",
"reason": "Failed to get agent index"
}
],
"type": "status_exception",
"reason": "Failed to get agent index"
},
"status": 404
}
```
4 changes: 4 additions & 0 deletions _ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,10 @@ DELETE /_plugins/_ml/memory_containers/SdjmmpgBOh0h20Y9kWuN?delete_memories=sess
}
```

## Error responses

If you attempt to delete a memory container that doesn't exist, the API behavior may vary. Ensure that the memory container exists before attempting to delete it.
Copy link
Copy Markdown
Contributor

@ylwu-amzn ylwu-amzn Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

may vary is vague . @b4sjoo, can you share what will exactly happen?

Copy link
Copy Markdown
Collaborator Author

@kolchfa-aws kolchfa-aws Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the code, there is a 500 error path and 404 error path. The 404 error path only occurs if the container passes the initial retrieval check but then fails during the actual deletion operation, which is less common. I think a 404 should be returned in both cases. Let me open an issue in the ml-commons repo.

Copy link
Copy Markdown
Collaborator Author

@kolchfa-aws kolchfa-aws Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's the ml-commons issue opensearch-project/ml-commons#4706

Copy link
Copy Markdown
Contributor

@b4sjoo b4sjoo Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right this is a bug. 404 is expected output here

Copy link
Copy Markdown
Collaborator Author

@kolchfa-aws kolchfa-aws Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Should I document the current behavior or can we put in the fix for this soon in the ml-commons repo? @ylwu-amzn Please let me know.


## Response fields

The following table lists all response body fields.
Expand Down
20 changes: 20 additions & 0 deletions _ml-commons-plugin/api/agentic-memory-apis/delete-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,26 @@ DELETE /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/history/eMx
}
```

### Error responses

If you attempt to delete a memory from a container that doesn't exist, OpenSearch returns a 404 Not Found error:

```json
{
"error": {
"root_cause": [
{
"type": "status_exception",
"reason": "Memory container not found"
}
],
"type": "status_exception",
"reason": "Memory container not found"
},
"status": 404
}
```

### Response fields

The following table lists all response body fields.
Expand Down
20 changes: 20 additions & 0 deletions _ml-commons-plugin/api/connector-apis/delete-connector.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,24 @@ DELETE /_plugins/_ml/connectors/KsAo1YsB0jLkkocY6j4U
"_seq_no" : 27,
"_primary_term" : 18
}
```

## Error responses

If you attempt to delete a connector that doesn't exist, OpenSearch returns a 404 Not Found error:

```json
{
"error": {
"root_cause": [
{
"type": "status_exception",
"reason": "Failed to find connector"
}
],
"type": "status_exception",
"reason": "Failed to find connector"
},
"status": 404
}
```
20 changes: 20 additions & 0 deletions _ml-commons-plugin/api/context-management-apis/delete-context-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,26 @@ DELETE /_plugins/_ml/context_management/advanced-context-management
}
```

## Error responses

If you attempt to delete a context management configuration that doesn't exist, the API returns a 404 error indicating the resource was not found:

```json
{
"error": {
"root_cause": [
{
"type": "status_exception",
"reason": "Context management template not found: sliding_window_max_40000_tokens_managers123"
}
],
"type": "status_exception",
"reason": "Context management template not found: sliding_window_max_40000_tokens_managers123"
},
"status": 404
}
```

## Related documentation

For more information, see [Context management]({{site.url}}{{site.baseurl}}/ml-commons-plugin/context-management/).
28 changes: 28 additions & 0 deletions _ml-commons-plugin/api/controller-apis/delete-controller.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,34 @@ DELETE /_plugins/_ml/controllers/MzcIJX8BA7mbufL6DOwl
}
```

## Error responses

If you attempt to delete a controller when the controller index doesn't exist, OpenSearch returns a 404 Not Found error:

```json
{
"error": {
"root_cause": [
{
"type": "index_not_found_exception",
"reason": "no such index [.plugins-ml-controller]",
"index": ".plugins-ml-controller",
"resource.id": ".plugins-ml-controller",
"resource.type": "index_expression",
"index_uuid": "_na_"
}
],
"type": "index_not_found_exception",
"reason": "no such index [.plugins-ml-controller]",
"index": ".plugins-ml-controller",
"resource.id": ".plugins-ml-controller",
"resource.type": "index_expression",
"index_uuid": "_na_"
},
"status": 404
}
```

## Required permissions

If you use the Security plugin, make sure you have the appropriate permissions: `cluster:admin/opensearch/ml/controllers/delete`.
14 changes: 13 additions & 1 deletion _ml-commons-plugin/api/memory-apis/delete-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,16 @@ DELETE /_plugins/_ml/memory/MzcIJX8BA7mbufL6DOwl
{
"success": true
}
```
```

## Response for non-existent memories

The delete memory operation is idempotent. If you attempt to delete a memory that doesn't exist, the operation still returns success:

```json
{
"success": true
}
```

This behavior allows delete operations to be safely retried without causing errors.
20 changes: 20 additions & 0 deletions _ml-commons-plugin/api/model-apis/delete-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,26 @@ DELETE /_plugins/_ml/models/MzcIJX8BA7mbufL6DOwl
}
```

## Error responses

If you attempt to delete a model that doesn't exist, OpenSearch returns a 404 Not Found error:

```json
{
"error": {
"root_cause": [
{
"type": "status_exception",
"reason": "Failed to find model"
}
],
"type": "status_exception",
"reason": "Failed to find model"
},
"status": 404
}
```

## Safely deleting a model
Introduced 2.19
{: .label .label-purple }
Expand Down
23 changes: 23 additions & 0 deletions _ml-commons-plugin/api/model-group-apis/delete-model-group.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,26 @@ DELETE _plugins/_ml/model_groups/<model_group_id>
"_primary_term": 23
}
```

## Response for non-existent model groups

If you attempt to delete a model group that doesn't exist, the delete operation succeeds and returns `"result": "not_found"`:

```json
{
"_index": ".plugins-ml-model-group",
"_id": "l8nnQogByXnLJ-QNpEk2",
"_version": 1,
"result": "not_found",
"forced_refresh": true,
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"_seq_no": 5,
"_primary_term": 25
}
```

This idempotent behavior ensures that delete operations can be safely retried without causing errors.
20 changes: 20 additions & 0 deletions _ml-commons-plugin/api/tasks-apis/delete-task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,24 @@ DELETE /_plugins/_ml/tasks/xQRYLX8BydmmU1x6nuD3
"_seq_no" : 42,
"_primary_term" : 7
}
```

## Error responses

If you attempt to delete a task that doesn't exist, OpenSearch returns a 404 Not Found error:

```json
{
"error": {
"root_cause": [
{
"type": "status_exception",
"reason": "Failed to find task"
}
],
"type": "status_exception",
"reason": "Failed to find task"
},
"status": 404
}
```
⚡