home-assistant/core · error · HomeAssistantError

api_error

Error message

api_error

What it means

A HomeAssistantError with translation key 'api_error' raised when the streaming chat call raises anthropic.APIConnectionError — the SDK could not reach Anthropic at all (DNS, TLS, refused connection). The handler logs at info level and calls coordinator.mark_connection_error() so the integration's connection state reflects the outage.

Source

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

                                output_tool=structure_name or None,
                            ),
                        )
                    ]
                )
                cast(list[MessageParam], model_args["messages"]).extend(new_messages)
            except anthropic.AuthenticationError as err:
                # Trigger coordinator to confirm the auth failure
                # and trigger the reauth flow.
                await coordinator.async_request_refresh()
                raise HomeAssistantError(
                    translation_domain=DOMAIN,
                    translation_key="api_authentication_error",
                    translation_placeholders={"message": err.message},
                ) from err
            except anthropic.APIConnectionError as err:
                LOGGER.info("Connection error while talking to Anthropic: %s", err)
                coordinator.mark_connection_error()
                raise HomeAssistantError(
                    translation_domain=DOMAIN,
                    translation_key="api_error",
                    translation_placeholders={"message": err.message},
                ) from err
            except anthropic.AnthropicError as err:
                # Non-connection error, mark connection as healthy
                coordinator.async_set_updated_data(coordinator.data)
                LOGGER.error("Error while talking to Anthropic: %s", err)
                raise HomeAssistantError(
                    translation_domain=DOMAIN,
                    translation_key="api_error",
                    translation_placeholders={
                        "message": err.message
                        if isinstance(err, anthropic.APIError)
                        else str(err)
                    },
                ) from err

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify egress to api.anthropic.com:443 (curl -I https://api.anthropic.com) from the Home Assistant host
2. Allowlist api.anthropic.com on firewalls/proxies and ensure the CA bundle trusts the presented certificate
3. Check DNS resolution inside containerized installs

import socket

def host_reachable(host: str = "api.anthropic.com", port: int = 443, timeout: float = 3.0) -> bool:
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return True
    except OSError:
        return False

import anthropic

def is_connection_error(err: BaseException) -> bool:
    return isinstance(err, anthropic.APIConnectionError)

except anthropic.APIConnectionError as err:
    LOGGER.info("Connection error while talking to Anthropic: %s", err)
    coordinator.mark_connection_error()
    raise HomeAssistantError(...) from err

When it happens

Trigger: messages.create with stream=True failing to connect: no internet, DNS failure for api.anthropic.com, firewall/proxy blocking egress, or TLS interception with an untrusted certificate.

Common situations: Local network outage, corporate proxy requiring allowlisting of api.anthropic.com, container deployments without DNS configured, self-signed MITM proxies.

Related errors

• cannot_connect
• setup_connection_error
• Credential is already linked to a user
• Unable find multi-factor auth module: {mfa_module_id}
• update_error

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