home-assistant/core · warning · HomeAssistantError

api_refusal

Error message

api_refusal

What it means

A HomeAssistantError with translation key 'api_refusal' raised in on_message_delta_event when the Anthropic message stream ends with stop_reason == 'refusal'. Anthropic models can refuse to continue generating when safety systems flag the conversation; the integration surfaces this as a user-visible error instead of returning partial content.

Source

Thrown at homeassistant/components/anthropic/entity.py:870

                    "tool_calls": [
                        llm.ToolInput(
                            id=self._current_tool_block["id"],
                            tool_name=self._current_tool_block["name"],
                            tool_args=self._current_tool_block["input"],
                            external=self._current_tool_block["type"]
                            == "server_tool_use",
                        )
                    ]
                }
            )
            self._current_tool_block = None

    def on_message_delta_event(self, delta: Delta, usage: MessageDeltaUsage) -> None:
        """Handle RawMessageDeltaEvent."""
        self._chat_log.async_trace(self._create_token_stats(self._input_usage, usage))
        self._content_details.container = delta.container
        if delta.stop_reason == "refusal":
            raise HomeAssistantError(
                translation_domain=DOMAIN, translation_key="api_refusal"
            )

    def on_message_stop_event(self) -> None:
        """Handle RawMessageStopEvent."""
        if self._content_details:
            self._content_details.delete_empty()
            self._buffer.append({"native": self._content_details})
        self._content_details = ContentDetails()
        self._content_details.add_citation_detail()

    def _create_token_stats(
        self, input_usage: Usage | None, response_usage: MessageDeltaUsage
    ) -> dict[str, Any]:
        """Create token stats for conversation agent tracing."""
        input_tokens = 0
        cached_input_tokens = 0
        if input_usage:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Rephrase the request to avoid the content that triggered the safety refusal
  2. Clear or trim the conversation history that may be accumulating flagged context
  3. If false-positive, report via Anthropic feedback channels and retry with different wording
Defensive patterns

Strategy: try-catch

Try / catch

try:
    async for delta in stream:
        ...
except HomeAssistantError as err:
    if err.translation_key == "api_refusal":
        # inform the user and offer to rephrase; do not retry identically
        ...

Prevention

When it happens

Trigger: Streaming a completion where the final MessageDeltaEvent carries delta.stop_reason='refusal' — prompts containing content that trips Anthropic safety filters, or attempts to extract system-prompt/copyrighted material via the conversation agent.

Common situations: Users asking the voice/assistant entity for disallowed content, attachments or chat history that accumulate into a flagged context, or overly adversarial prompt engineering.

Related errors

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/3bad59d6384456b7. Report an issue: GitHub.