feat: Use Structured Errors in Responses and Conversations API (#4879)

## Summary

Replace ValueError/Exception with LlamaStackError subclasses in
Responses and Conversations APIs for predictable HTTP status codes (400,
404, 500, 503).

**Responses API**
- `InvalidParameterError` (400) for parameter validation: conversation
ID format, mutually exclusive `previous_response_id` + `conversation`,
prompt variables, temperature range, MCP Authorization in headers
- `InternalServerError` (500) for stream failures: `response.failed` in
non-streaming mode, multiple terminal events, stream never reaching
terminal state
- `ServiceNotEnabledError` (503) for guardrails without Safety API
- `ResponseNotFoundError` (404) replaces `ValueError` for missing
responses
- Remove dead `max_tool_calls < 1` guard (Pydantic enforces at API
boundary)

**Conversations API**
- `InvalidParameterError` (400) for invalid `conversation_id` format and
empty `conversation_id`/`item_id`
- `ConversationItemNotFoundError` (404) for missing items in
retrieve/delete
- Replace `InvalidConversationIdError` with `InvalidParameterError` for
consistency

**Other**
- MCP auth test catches both `llama_stack_client.BadRequestError` and
`openai.BadRequestError`
- `logger.error` with `extra=` context on failure paths for operator
debugging
- Docstring improvements for `ResourceNotFoundError`,
`InvalidParameterError`, `ServiceNotEnabledError`

## Stack

This is PR 2/4 in the error message consistency series (split from
#3913). Depends on #4878 (included in this branch).

1. Error types foundation (#4878) — merge first
2. **This PR** — Responses and Conversations API error handling
3. Record/replay error support (#record-replay-errors)
4. Integration tests (#error-integration-tests)

## Test plan

- [x] Unit tests updated for structured error types
(`InvalidParameterError`, `ServiceNotEnabledError`,
`InternalServerError`, `ResponseNotFoundError`,
`ConversationItemNotFoundError`)
- [x] `test_errors.py`: HTTP status code tests for all new error types
(400, 404, 500, 503)
- [x] `test_conversations.py`: expect `InvalidParameterError` for
invalid ID format and empty params
- [x] `test_mcp_authentication.py`: expect `BadRequestError` from both
OpenAI and llama-stack clients
- [x] Unit test for `response.failed` → `InternalServerError` in
non-streaming mode
- [x] All pre-commit hooks pass (ruff, mypy, API spec codegen, license
checks)
- [x] CI passes

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: iamemilio

src/llama_stack/core/conversations/conversations.py

@@ -14,7 +14,12 @@
 from llama_stack.core.storage.sqlstore.authorized_sqlstore import AuthorizedSqlStore
 from llama_stack.core.storage.sqlstore.sqlstore import sqlstore_impl
 from llama_stack.log import get_logger
-from llama_stack_api.common.errors import ConversationNotFoundError
+from llama_stack_api import (
+    ConversationItemNotFoundError,
+    ConversationNotFoundError,
+    InvalidParameterError,
+    ServiceNotEnabledError,
+)
 from llama_stack_api.conversations import (
     AddItemsRequest,
     Conversation,
@@ -65,7 +70,7 @@ def __init__(self, config: ConversationServiceConfig, deps: dict[Any, Any]):
         # Use conversations store reference from run config
         conversations_ref = config.config.storage.stores.conversations
         if not conversations_ref:
-            raise ValueError("storage.stores.conversations must be configured in run config")
+            raise ServiceNotEnabledError("storage.stores.conversations")
 
         base_sql_store = sqlstore_impl(conversations_ref)
         self.sql_store = AuthorizedSqlStore(base_sql_store, self.policy)
@@ -176,9 +181,7 @@ async def openai_delete_conversation(self, request: DeleteConversationRequest) -
     def _validate_conversation_id(self, conversation_id: str) -> None:
         """Validate conversation ID format."""
         if not conversation_id.startswith("conv_"):
-            raise ValueError(
-                f"Invalid 'conversation_id': '{conversation_id}'. Expected an ID that begins with 'conv_'."
-            )
+            raise InvalidParameterError("conversation_id", conversation_id, "Conversation ID must begin with 'conv_'.")
 
     def _get_or_generate_item_id(self, item: ConversationItem, item_dict: dict) -> str:
         """Get existing item ID or generate one if missing."""
@@ -242,29 +245,25 @@ async def add_items(self, conversation_id: str, request: AddItemsRequest) -> Con
     async def retrieve(self, request: RetrieveItemRequest) -> ConversationItem:
         """Retrieve a conversation item."""
         if not request.conversation_id:
-            raise ValueError(
-                f"Expected a non-empty value for `conversation_id` but received {request.conversation_id!r}"
-            )
+            raise InvalidParameterError("conversation_id", request.conversation_id, "Must be a non-empty string.")
         if not request.item_id:
-            raise ValueError(f"Expected a non-empty value for `item_id` but received {request.item_id!r}")
+            raise InvalidParameterError("item_id", request.item_id, "Must be a non-empty string.")
 
         # Get item from conversation_items table
         record = await self.sql_store.fetch_one(
             table="conversation_items", where={"id": request.item_id, "conversation_id": request.conversation_id}
         )
 
         if record is None:
-            raise ValueError(f"Item {request.item_id} not found in conversation {request.conversation_id}")
+            raise ConversationItemNotFoundError(request.item_id, request.conversation_id)
 
         adapter: TypeAdapter[ConversationItem] = TypeAdapter(ConversationItem)
         return adapter.validate_python(record["item_data"])
 
     async def list_items(self, request: ListItemsRequest) -> ConversationItemList:
         """List items in the conversation."""
         if not request.conversation_id:
-            raise ValueError(
-                f"Expected a non-empty value for `conversation_id` but received {request.conversation_id!r}"
-            )
+            raise InvalidParameterError("conversation_id", request.conversation_id, "Must be a non-empty string.")
 
         # check if conversation exists
         await self.get_conversation(GetConversationRequest(conversation_id=request.conversation_id))
@@ -300,11 +299,9 @@ async def list_items(self, request: ListItemsRequest) -> ConversationItemList:
     async def openai_delete_conversation_item(self, request: DeleteItemRequest) -> ConversationItemDeletedResource:
         """Delete a conversation item."""
         if not request.conversation_id:
-            raise ValueError(
-                f"Expected a non-empty value for `conversation_id` but received {request.conversation_id!r}"
-            )
+            raise InvalidParameterError("conversation_id", request.conversation_id, "Must be a non-empty string.")
         if not request.item_id:
-            raise ValueError(f"Expected a non-empty value for `item_id` but received {request.item_id!r}")
+            raise InvalidParameterError("item_id", request.item_id, "Must be a non-empty string.")
 
         _ = await self._get_validated_conversation(request.conversation_id)
 
@@ -313,7 +310,7 @@ async def openai_delete_conversation_item(self, request: DeleteItemRequest) -> C
         )
 
         if record is None:
-            raise ValueError(f"Item {request.item_id} not found in conversation {request.conversation_id}")
+            raise ConversationItemNotFoundError(request.item_id, request.conversation_id)
 
         await self.sql_store.delete(
             table="conversation_items", where={"id": request.item_id, "conversation_id": request.conversation_id}

src/llama_stack/providers/inline/agents/meta_reference/responses/openai_responses.py

@@ -25,7 +25,8 @@
     Conversations,
     Files,
     Inference,
-    InvalidConversationIdError,
+    InternalServerError,
+    InvalidParameterError,
     ListItemsRequest,
     ListOpenAIResponseInputItem,
     ListOpenAIResponseObject,
@@ -54,6 +55,7 @@
     ResponseItemInclude,
     ResponseTruncation,
     Safety,
+    ServiceNotEnabledError,
     ToolGroups,
     ToolRuntime,
     VectorIO,
@@ -304,7 +306,11 @@ async def _prepend_prompt(
         # Validate that all provided variables exist in the prompt
         for name in openai_response_prompt.variables.keys():
             if name not in cur_prompt_variables:
-                raise ValueError(f"Variable {name} not found in prompt {openai_response_prompt.id}")
+                raise InvalidParameterError(
+                    "prompt.variables",
+                    name,
+                    f"Variable not defined in prompt '{openai_response_prompt.id}'.",
+                )
 
         # Separate text and media variables
         text_substitutions = {}
@@ -581,29 +587,31 @@ async def create_openai_response(
                 if isinstance(tool, OpenAIResponseInputToolMCP) and tool.headers:
                     for key in tool.headers.keys():
                         if key.lower() == "authorization":
-                            raise ValueError(
-                                "Authorization header cannot be passed via 'headers'. "
-                                "Please use the 'authorization' parameter instead."
+                            raise InvalidParameterError(
+                                f"tools[server_label={tool.server_label!r}].headers",
+                                key,
+                                "Authorization credentials must be passed via the 'authorization' parameter, not 'headers'.",
                             )
 
         guardrail_ids = extract_guardrail_ids(guardrails) if guardrails else []
 
         # Validate that Safety API is available if guardrails are requested
         if guardrail_ids and self.safety_api is None:
-            raise ValueError(
-                "Cannot process guardrails: Safety API is not configured.\n\n"
-                "To use guardrails, ensure the Safety API is configured in your stack, or remove "
-                "the 'guardrails' parameter from your request."
+            raise ServiceNotEnabledError(
+                "Safety API",
+                provider_specific_message="Ensure the Safety API is enabled in your stack, otherwise remove the 'guardrails' parameter from your request.",
             )
 
         if conversation is not None:
             if previous_response_id is not None:
-                raise ValueError(
-                    "Mutually exclusive parameters: 'previous_response_id' and 'conversation'. Ensure you are only providing one of these parameters."
+                raise InvalidParameterError(
+                    "previous_response_id, conversation",
+                    "previous_response_id and conversation are both provided",
+                    "Provide only one of these parameters.",
                 )
 
             if not conversation.startswith("conv_"):
-                raise InvalidConversationIdError(conversation)
+                raise InvalidParameterError("conversation", conversation, "Expected an ID that begins with 'conv_'.")
 
         if max_tool_calls is not None and max_tool_calls < 1:
             raise ValueError(f"Invalid {max_tool_calls=}; should be >= 1")
@@ -668,32 +676,51 @@ async def create_openai_response(
             final_response = None
             final_event_type = None
             failed_response = None
-
             async for stream_chunk in stream_gen:
                 match stream_chunk.type:
                     case "response.completed" | "response.incomplete":
                         if final_response is not None:
-                            raise ValueError(
-                                "The response stream produced multiple terminal responses! "
-                                f"Earlier response from {final_event_type}"
+                            logger.error(
+                                "The response stream produced multiple terminal events, when it should produce exactly one.",
+                                extra={
+                                    "response_id": stream_chunk.response.id,
+                                    "first_terminal_event": final_event_type,
+                                    "second_terminal_event": stream_chunk.type,
+                                    "model": model,
+                                    "conversation": conversation,
+                                    "previous_response_id": previous_response_id,
+                                },
                             )
+                            raise InternalServerError()
                         final_response = stream_chunk.response
                         final_event_type = stream_chunk.type
                     case "response.failed":
                         failed_response = stream_chunk.response
+                        error_message = (
+                            failed_response.error.message
+                            if failed_response.error
+                            else "response failed but no error message was provided"
+                        )
+                        logger.error(
+                            "response creation failed",
+                            extra={
+                                "error_message": error_message,
+                                "response_id": failed_response.id,
+                                "model": model,
+                            },
+                        )
+                        # Surface the provider message — it may be actionable (e.g. context window exceeded)
+                        # and is already visible to callers in streaming mode via the response.failed event.
+                        raise InternalServerError(error_message)
                     case _:
                         pass  # Other event types don't have .response
 
-            if failed_response is not None:
-                error_message = (
-                    failed_response.error.message
-                    if failed_response and failed_response.error
-                    else "Response stream failed without error details"
-                )
-                raise RuntimeError(f"OpenAI response failed: {error_message}")
-
             if final_response is None:
-                raise ValueError("The response stream never reached a terminal state")
+                logger.error(
+                    "The response stream never reached a terminal state",
+                    extra={"model": model, "conversation": conversation, "previous_response_id": previous_response_id},
+                )
+                raise InternalServerError()
             # Set background=False for non-background responses
             final_response.background = False
             return final_response

src/llama_stack/providers/utils/responses/responses_store.py

@@ -10,6 +10,7 @@
 from llama_stack.core.storage.sqlstore.sqlstore import sqlstore_impl
 from llama_stack.log import get_logger
 from llama_stack_api import (
+    InvalidParameterError,
     ListOpenAIResponseInputItem,
     ListOpenAIResponseObject,
     OpenAIDeleteResponseObject,
@@ -18,6 +19,7 @@
     OpenAIResponseObject,
     OpenAIResponseObjectWithInput,
     Order,
+    ResponseInputItemNotFoundError,
     ResponseNotFoundError,
 )
 from llama_stack_api.internal.sqlstore import ColumnDefinition, ColumnType
@@ -193,7 +195,7 @@ async def get_response_object(self, response_id: str) -> _OpenAIResponseObjectWi
         if not row:
             # SecureSqlStore will return None if record doesn't exist OR access is denied
             # This provides security by not revealing whether the record exists
-            raise ResponseNotFoundError(response_id)
+            raise ResponseNotFoundError(response_id) from None
 
         return _OpenAIResponseObjectWithInputAndMessages(**row["response_object"])
 
@@ -268,7 +270,11 @@ async def list_response_input_items(
         if include:
             raise NotImplementedError("Include is not supported yet")
         if before and after:
-            raise ValueError("Cannot specify both 'before' and 'after' parameters")
+            raise InvalidParameterError(
+                "before/after",
+                f"before={before!r}, after={after!r}",
+                "Cannot specify both 'before' and 'after' parameters",
+            )
 
         response_with_input_and_messages = await self.get_response_object(response_id)
         items = response_with_input_and_messages.input
@@ -289,9 +295,9 @@ async def list_response_input_items(
                     break
 
             if after and start_index == 0:
-                raise ValueError(f"Input item with id '{after}' not found for response '{response_id}'")
+                raise ResponseInputItemNotFoundError(after, response_id)
             if before and end_index == len(items):
-                raise ValueError(f"Input item with id '{before}' not found for response '{response_id}'")
+                raise ResponseInputItemNotFoundError(before, response_id)
 
         items = items[start_index:end_index]
 

src/llama_stack_api/__init__.py

@@ -98,14 +98,18 @@
     ConflictError,
     ConnectorNotFoundError,
     ConnectorToolNotFoundError,
+    ConversationItemNotFoundError,
     ConversationNotFoundError,
     DatasetNotFoundError,
-    InvalidConversationIdError,
+    InternalServerError,
+    InvalidParameterError,
     ModelNotFoundError,
     ModelTypeError,
     OpenAIFileObjectNotFoundError,
     ResourceNotFoundError,
+    ResponseInputItemNotFoundError,
     ResponseNotFoundError,
+    ServiceNotEnabledError,
     TokenValidationError,
     ToolGroupNotFoundError,
     UnsupportedModelError,
@@ -653,6 +657,7 @@
     "Connector",
     "ConnectorNotFoundError",
     "ConnectorToolNotFoundError",
+    "ConversationItemNotFoundError",
     "ConversationNotFoundError",
     "ConnectorInput",
     "Connectors",
@@ -736,11 +741,12 @@
     "InsertChunksRequest",
     "Inspect",
     "InspectProviderRequest",
+    "InternalServerError",
     "Admin",
     "Int4QuantizationConfig",
     "InterleavedContent",
     "InterleavedContentItem",
-    "InvalidConversationIdError",
+    "InvalidParameterError",
     "is_generic_list",
     "is_type_optional",
     "is_type_union",
@@ -1017,6 +1023,8 @@
     "RerankResponse",
     "Resource",
     "ResourceNotFoundError",
+    "ResponseInputItemNotFoundError",
+    "ResponseNotFoundError",
     "ResourceType",
     "ResponseFormat",
     "ResponseFormatType",
@@ -1059,6 +1067,7 @@
     "SchemaInfo",
     "SchemaOptions",
     "SearchRankingOptions",
+    "ServiceNotEnabledError",
     "Shield",
     "ShieldInput",
     "ShieldStore",