"""网关内部异常类型（ARCH §4.5）。

适配器把厂商的可重试故障（限流/超时/5xx）翻译为 `TransientProviderError`，
网关据此决定退避重试 / 切回退链。非瞬时错误（内容策略拒绝等）由适配器抛
`AppError` 或原样上抛，网关不盲目重试。

`ww_shared.AppError(ErrorCode.RATE_LIMITED)` 也被网关视作可重试/可回退（限流即瞬时）。
"""

from __future__ import annotations


class TransientProviderError(Exception):
    """瞬时、可重试的 provider 故障（429/超时/5xx/连接错误）。

    适配器在 `except` 厂商异常时包装抛出，携带原始 provider 名便于日志/熔断归因。
    """

    def __init__(self, message: str, *, provider: str | None = None) -> None:
        super().__init__(message)
        self.message = message
        self.provider = provider