better rate limit forwarding

make sure balance is set correctly

Makefile

@@ -98,7 +98,7 @@ docker-down:
 lint:
 	@echo "🔍 Running linting checks..."
 	$(RUFF) check .
-	$(MYPY) routstr/ --ignore-missing-imports
+	$(MYPY) .
 
 format:
 	@echo "✨ Formatting code..."
@@ -107,7 +107,7 @@ format:
 
 type-check:
 	@echo "🔎 Running type checks..."
-	$(MYPY) routstr/ --ignore-missing-imports
+	$(MYPY) .
 
 # Development setup
 dev-setup:
@@ -234,7 +234,7 @@ ci-test:
 ci-lint:
 	@echo "🤖 Running CI linting..."
 	$(RUFF) check . --exit-non-zero-on-fix
-	$(MYPY) routstr/ --ignore-missing-imports --no-error-summary
+	$(MYPY) . --no-error-summary
 
 # Debug helpers
 test-debug:

routstr/auth.py

@@ -709,12 +709,18 @@ async def revert_pay_for_request(
 
 
 async def adjust_payment_for_tokens(
-    key: ApiKey, response_data: dict, session: AsyncSession, deducted_max_cost: int
+    key: ApiKey,
+    response_data: dict,
+    session: AsyncSession,
+    deducted_max_cost: int,
 ) -> dict:
     """
     Adjusts the payment based on token usage in the response.
     This is called after the initial payment and the upstream request is complete.
     Returns cost data to be included in the response.
+
+    The response's usage object is normalized with the default union parser in
+    ``calculate_cost``.
     """
     billing_key = await get_billing_key(key, session)
     model = response_data.get("model", "unknown")
@@ -797,7 +803,7 @@ async def adjust_payment_for_tokens(
                     extra={"error": str(e), "fee_msats": fee_msats},
                 )
 
-    match await calculate_cost(response_data, deducted_max_cost, session):
+    match await calculate_cost(response_data, deducted_max_cost):
         case MaxCostData() as cost:
             logger.debug(
                 "Using max cost data (no token adjustment)",

routstr/core/exceptions.py

@@ -7,11 +7,26 @@ logger = get_logger(__name__)
 
 
 class UpstreamError(Exception):
-    """Exception raised when an upstream provider fails."""
+    """Exception raised when an upstream provider fails.
 
-    def __init__(self, message: str, status_code: int = 502):
+    ``code`` carries a stable, machine-readable classification (e.g.
+    ``UPSTREAM_RATE_LIMIT``) so callers can distinguish failure kinds without
+    string-matching the message. ``details`` holds optional structured,
+    redaction-safe context. Both default to ``None`` for backwards
+    compatibility.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 502,
+        code: str | None = None,
+        details: dict[str, object] | None = None,
+    ):
         self.message = message
         self.status_code = status_code
+        self.code = code
+        self.details = details
         super().__init__(message)
 
 

routstr/core/logging.py

@@ -51,6 +51,8 @@ from pythonjsonlogger import jsonlogger
 from rich.console import Console
 from rich.logging import RichHandler
 
+from .redaction import redact_obj, redact_org_ids
+
 # Only use RichHandler when stdout is a real TTY. In non-TTY contexts
 # (docker logs, pipes, CI) Rich pads every line to width and wraps long
 # records, producing visually-empty trailing whitespace and split records.
@@ -180,6 +182,37 @@ class RequestIdFilter(logging.Filter):
         return True
 
 
+# Standard ``LogRecord`` attributes that are never user-supplied ``extra``
+# fields; skipped when redacting structured extras (``msg``/``message`` are
+# handled separately above).
+_NON_EXTRA_RECORD_ATTRS = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "lineno",
+        "funcName",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "processName",
+        "process",
+        "taskName",
+        "message",
+    }
+)
+
+
 class SecurityFilter(logging.Filter):
     """Filter to remove sensitive information from logs."""
 
@@ -203,6 +236,7 @@ class SecurityFilter(logging.Filter):
         """Filter out sensitive information from log records."""
         try:
             message = record.getMessage()
+            message = redact_org_ids(message)
             standalone_patterns = [
                 r"Bearer\s+([a-zA-Z0-9_\-\.]{10,})",  # Bearer token (must be 10 characters or more to reduce false-positives)
                 r"cashu[A-Z]+([a-zA-Z0-9_\-\.=/+]+)",  # Cashu tokens
@@ -224,6 +258,16 @@ class SecurityFilter(logging.Filter):
             record.msg = message
             record.args = ()
 
+            # Structured `extra={...}` fields are emitted by the JSON formatter
+            # straight from the record dict and never pass through the message
+            # formatting above. Redact organization IDs from any string-valued
+            # extra so they cannot leak via structured logs.
+            for attr, value in list(record.__dict__.items()):
+                if attr in _NON_EXTRA_RECORD_ATTRS:
+                    continue
+                if isinstance(value, (str, dict, list, tuple)):
+                    record.__dict__[attr] = redact_obj(value)
+
         except Exception:
             pass
 

routstr/core/redaction.py

@@ -0,0 +1,51 @@
+"""Redaction helpers for sensitive provider identifiers.
+
+Single source of truth for stripping account-scoped identifiers (e.g. OpenAI
+organization IDs) from any text before it is logged, returned to a caller, or
+written to an audit entry.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# OpenAI-style organization identifiers look like ``org-<base62>``. Require at
+# least 6 trailing chars so the already-redacted literal ``org-[REDACTED]`` is
+# never re-matched (``[`` is not in the character class).
+_ORG_ID_PATTERN = re.compile(r"\borg-[A-Za-z0-9]{6,}\b")
+
+ORG_ID_PLACEHOLDER = "org-[REDACTED]"
+
+
+def redact_org_ids(text: str) -> str:
+    """Replace OpenAI-style organization IDs with ``org-[REDACTED]``.
+
+    Args:
+        text: Arbitrary text that may embed an ``org-*`` identifier.
+
+    Returns:
+        The text with every organization ID replaced. Non-string input is
+        returned unchanged after coercion to ``str``.
+    """
+    if not text:
+        return text
+    return _ORG_ID_PATTERN.sub(ORG_ID_PLACEHOLDER, text)
+
+
+def redact_obj(obj: Any) -> Any:
+    """Recursively redact organization IDs in arbitrary nested structures.
+
+    Strings are redacted in place; dicts and lists/tuples are walked so that
+    identifiers nested inside structured payloads (e.g. log ``extra`` fields or
+    error ``details``) are also stripped. Other types are returned unchanged.
+    """
+    if isinstance(obj, str):
+        return redact_org_ids(obj)
+    if isinstance(obj, dict):
+        return {key: redact_obj(value) for key, value in obj.items()}
+    if isinstance(obj, list):
+        return [redact_obj(value) for value in obj]
+    if isinstance(obj, tuple):
+        return tuple(redact_obj(value) for value in obj)
+    return obj

routstr/payment/cost_calculation.py

@@ -3,9 +3,17 @@ import math
 from pydantic.v1 import BaseModel
 
 from ..core import get_logger
-from ..core.db import AsyncSession
 from ..core.settings import settings
 from .price import sats_usd_price
+from .usage import normalize_usage, parse_token_count
+
+__all__ = [
+    "CostData",
+    "CostDataError",
+    "MaxCostData",
+    "calculate_cost",
+    "parse_token_count",
+]
 
 logger = get_logger(__name__)
 
@@ -34,7 +42,8 @@ class CostDataError(BaseModel):
 
 
 async def calculate_cost(
-    response_data: dict, max_cost: int, session: AsyncSession
+    response_data: dict,
+    max_cost: int,
 ) -> CostData | MaxCostData | CostDataError:
     """Calculate the cost of an API request based on token usage.
 
@@ -44,6 +53,9 @@ async def calculate_cost(
 
     Returns:
         Cost data or error information
+
+    The response's usage object is normalized with the default union parser;
+    this function holds no vendor-dialect knowledge of its own.
     """
     logger.debug(
         "Starting cost calculation",
@@ -54,8 +66,9 @@ async def calculate_cost(
         },
     )
 
-    # Check for usage data
-    if "usage" not in response_data or response_data["usage"] is None:
+    usage = normalize_usage(response_data.get("usage"))
+
+    if usage is None:
         logger.warning(
             "No usage data in response — billing at MaxCostData with zero "
             "tokens. Dashboard will show this request as `(0+0)`. Most "
@@ -84,16 +97,14 @@ async def calculate_cost(
             cache_creation_msats=0,
         )
 
-    usage_data = response_data["usage"]
+    usage_data = response_data.get("usage") or {}
+    if not isinstance(usage_data, dict):
+        usage_data = {}
 
-    # Extract token counts
-    input_tokens = _extract_token_pair(usage_data, "prompt_tokens", "input_tokens")
-    output_tokens = _extract_token_pair(usage_data, "completion_tokens", "output_tokens")
-
-    # Extract cache tokens (handles OpenAI vs Anthropic formats)
-    cache_read_tokens, cache_creation_tokens, input_tokens = _extract_cache_tokens(
-        usage_data, input_tokens
-    )
+    input_tokens = usage.input_tokens
+    output_tokens = usage.output_tokens
+    cache_read_tokens = usage.cache_read_tokens
+    cache_creation_tokens = usage.cache_write_tokens
 
     # Try USD cost first
     usd_cost = _resolve_usd_cost(usage_data, response_data)
@@ -202,22 +213,6 @@ async def calculate_cost(
 # ============================================================================
 
 
-def parse_token_count(value: object) -> int:
-    """Parse a token count from various formats (int, float, str, bool)."""
-    if isinstance(value, bool):
-        return 0
-    if isinstance(value, int):
-        return max(0, value)
-    if isinstance(value, float):
-        return max(0, int(value))
-    if isinstance(value, str):
-        try:
-            return max(0, int(float(value)))
-        except ValueError:
-            return 0
-    return 0
-
-
 def _coerce_usd(value: object) -> float:
     """Coerce a value to USD float, handling various formats safely."""
     if value is None or isinstance(value, bool):
@@ -230,37 +225,6 @@ def _coerce_usd(value: object) -> float:
         return 0.0
 
 
-def _extract_token_pair(
-    usage_data: dict, standard_field: str, alt_field: str
-) -> int:
-    """Extract token count trying two field names in order."""
-    value = parse_token_count(usage_data.get(standard_field, 0))
-    if value > 0:
-        return value
-    return parse_token_count(usage_data.get(alt_field, 0))
-
-
-def _extract_cache_tokens(usage_data: dict, input_tokens: int) -> tuple[int, int, int]:
-    """Extract cache tokens, handling OpenAI vs Anthropic formats.
-
-    Returns: (cache_read_tokens, cache_creation_tokens, adjusted_input_tokens)
-    """
-    cache_read = parse_token_count(usage_data.get("cache_read_input_tokens", 0))
-    cache_creation = parse_token_count(
-        usage_data.get("cache_creation_input_tokens", 0)
-    )
-
-    # OpenAI: cache is included in input_tokens, subtract it
-    prompt_details = usage_data.get("prompt_tokens_details")
-    if isinstance(prompt_details, dict) and not cache_read:
-        openai_cached = parse_token_count(prompt_details.get("cached_tokens", 0))
-        if openai_cached:
-            cache_read = openai_cached
-            input_tokens = max(0, input_tokens - cache_read)
-
-    return cache_read, cache_creation, input_tokens
-
-
 def _resolve_usd_cost(usage_data: dict, response_data: dict) -> float:
     """Resolve USD cost with clear priority order.
 

routstr/payment/helpers.py

@@ -11,6 +11,8 @@ from PIL import Image
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from ..core import get_logger
+from ..core.exceptions import UpstreamError
+from ..core.redaction import redact_org_ids
 from ..core.settings import settings
 from ..wallet import deserialize_token_from_string
 
@@ -418,16 +420,27 @@ def create_error_response(
     status_code: int,
     request: Request,
     token: str | None = None,
+    code: str | int | None = None,
+    details: dict[str, object] | None = None,
 ) -> Response:
-    """Create a standardized error response."""
+    """Create a standardized error response.
+
+    ``code`` is a stable, machine-readable classification (e.g.
+    ``UPSTREAM_RATE_LIMIT``); when omitted it defaults to the HTTP status code
+    for backwards compatibility. ``details`` carries optional structured,
+    redaction-safe context.
+    """
+    error_obj: dict[str, object] = {
+        "message": redact_org_ids(message),
+        "type": error_type,
+        "code": code if code is not None else status_code,
+    }
+    if details is not None:
+        error_obj["details"] = details
     return Response(
         content=json.dumps(
             {
-                "error": {
-                    "message": message,
-                    "type": error_type,
-                    "code": status_code,
-                },
+                "error": error_obj,
                 "request_id": getattr(request.state, "request_id", "unknown"),
             }
         ),
@@ -435,3 +448,20 @@ def create_error_response(
         media_type="application/json",
         headers={"X-Cashu": token} if token else {},
     )
+
+
+def create_upstream_error_response(
+    error: UpstreamError,
+    request: Request,
+    fallback_status: int = 502,
+) -> Response:
+    """Build an error response from an :class:`UpstreamError`, preserving its
+    structured ``code``, ``details``, and original ``status_code``."""
+    return create_error_response(
+        "upstream_error",
+        str(error),
+        error.status_code or fallback_status,
+        request=request,
+        code=getattr(error, "code", None),
+        details=getattr(error, "details", None),
+    )

routstr/payment/models.py

@@ -85,6 +85,48 @@ class Model(BaseModel):
         return hash(self.id)
 
 
+def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
+    """Fill missing cache rates from litellm's bundled cost map.
+
+    The OpenRouter model feed omits ``input_cache_read``/``input_cache_write``
+    for many models (most DeepSeek entries, openai/gpt-4o, ...). Without a
+    cache rate, billing falls back to the full input rate, which overcharges
+    cache reads (DeepSeek hits are 10x cheaper) and undercharges Anthropic
+    cache writes (1.25x). litellm ships per-model USD rates keyed by the exact
+    OpenRouter id (deepseek/deepseek-chat) or by the bare model name
+    (gpt-4o, claude-sonnet-4-5), so both spellings are tried.
+
+    Rates already present (e.g. provided by OpenRouter) are authoritative and
+    never overwritten. Unknown models are returned unchanged.
+    """
+    needs_read = (pricing.input_cache_read or 0.0) <= 0.0
+    needs_write = (pricing.input_cache_write or 0.0) <= 0.0
+    if not (needs_read or needs_write):
+        return pricing
+
+    import litellm
+
+    info: dict | None = None
+    for key in (model_id, model_id.split("/", 1)[-1]):
+        candidate = litellm.model_cost.get(key)
+        if isinstance(candidate, dict):
+            info = candidate
+            break
+    if info is None:
+        return pricing
+
+    updated = Pricing.parse_obj(pricing.dict())
+    if needs_read:
+        read_rate = info.get("cache_read_input_token_cost")
+        if isinstance(read_rate, (int, float)) and read_rate > 0:
+            updated.input_cache_read = float(read_rate)
+    if needs_write:
+        write_rate = info.get("cache_creation_input_token_cost")
+        if isinstance(write_rate, (int, float)) and write_rate > 0:
+            updated.input_cache_write = float(write_rate)
+    return updated
+
+
 def _has_valid_pricing(model: dict) -> bool:
     """Check if model has valid pricing (not free, no negative values)."""
     pricing = model.get("pricing", {})

routstr/payment/usage.py

@@ -0,0 +1,131 @@
+"""Vendor-agnostic normalization of upstream usage objects.
+
+Upstream providers report token usage in vendor dialects that differ in field
+names and in whether cached tokens are included in the input count:
+
+* OpenAI / Azure / xAI / Groq / Moonshot / Qwen / Gemini-compat: cache reads in
+  ``prompt_tokens_details.cached_tokens``, included in ``prompt_tokens``.
+* OpenRouter: same as OpenAI plus cache *writes* in
+  ``prompt_tokens_details.cache_write_tokens``, also included in
+  ``prompt_tokens``.
+* litellm-normalized: same nesting, but names the write field
+  ``prompt_tokens_details.cache_creation_tokens`` (and additionally mirrors the
+  Anthropic top-level fields), with ``prompt_tokens`` as the grand total.
+* Anthropic native: ``cache_read_input_tokens`` / ``cache_creation_input_tokens``
+  top-level, additive to (not included in) ``input_tokens``.
+* DeepSeek: ``prompt_cache_hit_tokens`` / ``prompt_cache_miss_tokens``, with
+  ``prompt_tokens = hit + miss``.
+
+What decides whether cached tokens must be subtracted out of the input count is
+**which prompt field the vendor uses**, not which cache field appears:
+
+* ``prompt_tokens`` present -> cached + cache-write tokens are *included* in it
+  (OpenAI family, DeepSeek, OpenRouter, litellm); subtract both so
+  ``input_tokens`` holds only the regular-rate portion.
+* only ``input_tokens`` (Anthropic native) -> cached tokens are *additive*;
+  leave ``input_tokens`` untouched.
+
+``normalize_usage`` maps all of them onto one canonical ``NormalizedUsage``
+shape so billing code needs no vendor knowledge. The known dialects' field
+names do not collide, so a single union parser is safe; a vendor whose fields
+would genuinely conflict needs a dedicated branch here.
+"""
+
+from pydantic.v1 import BaseModel
+
+
+class NormalizedUsage(BaseModel):
+    """Canonical token usage: input_tokens never includes cached tokens."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+
+def parse_token_count(value: object) -> int:
+    """Parse a token count from various formats (int, float, str, bool)."""
+    if isinstance(value, bool):
+        return 0
+    if isinstance(value, int):
+        return max(0, value)
+    if isinstance(value, float):
+        return max(0, int(value))
+    if isinstance(value, str):
+        try:
+            return max(0, int(float(value)))
+        except ValueError:
+            return 0
+    return 0
+
+
+def _first_token_count(usage_data: dict, *fields: str) -> int:
+    """Return the first positive token count among the given fields."""
+    for field in fields:
+        value = parse_token_count(usage_data.get(field, 0))
+        if value > 0:
+            return value
+    return 0
+
+
+def _extract_cache_tokens(usage_data: dict) -> tuple[int, int]:
+    """Pull (cache_read, cache_write) across all known dialects.
+
+    Precedence (highest first), independent for reads and writes:
+
+    * Anthropic top-level: ``cache_read_input_tokens`` /
+      ``cache_creation_input_tokens``.
+    * Nested ``prompt_tokens_details``: ``cached_tokens`` for reads;
+      ``cache_creation_tokens`` (litellm) or ``cache_write_tokens``
+      (OpenRouter) for writes.
+    * DeepSeek: ``prompt_cache_hit_tokens`` for reads (no write concept).
+    """
+    cache_read = parse_token_count(usage_data.get("cache_read_input_tokens", 0))
+    cache_write = parse_token_count(usage_data.get("cache_creation_input_tokens", 0))
+
+    prompt_details = usage_data.get("prompt_tokens_details")
+    if isinstance(prompt_details, dict):
+        if not cache_read:
+            cache_read = parse_token_count(prompt_details.get("cached_tokens", 0))
+        if not cache_write:
+            cache_write = _first_token_count(
+                prompt_details, "cache_creation_tokens", "cache_write_tokens"
+            )
+
+    if not cache_read:
+        # DeepSeek: prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens
+        cache_read = parse_token_count(usage_data.get("prompt_cache_hit_tokens", 0))
+
+    return cache_read, cache_write
+
+
+def normalize_usage(usage_data: object) -> NormalizedUsage | None:
+    """Map a vendor usage dict onto the canonical shape, or None if absent.
+
+    Cached reads and writes are subtracted from the input count exactly once,
+    only for dialects that report a ``prompt_tokens`` grand total that already
+    includes them (OpenAI family, DeepSeek, OpenRouter, litellm). Anthropic
+    native reports them additively under ``input_tokens`` and is left untouched.
+    """
+    if not isinstance(usage_data, dict):
+        return None
+
+    output_tokens = _first_token_count(
+        usage_data, "completion_tokens", "output_tokens"
+    )
+    cache_read, cache_write = _extract_cache_tokens(usage_data)
+
+    # ``prompt_tokens`` is the inclusive grand total; ``input_tokens`` (Anthropic
+    # native) excludes cached tokens. The field chosen decides whether to subtract.
+    if "prompt_tokens" in usage_data:
+        input_tokens = parse_token_count(usage_data.get("prompt_tokens", 0))
+        input_tokens = max(0, input_tokens - cache_read - cache_write)
+    else:
+        input_tokens = parse_token_count(usage_data.get("input_tokens", 0))
+
+    return NormalizedUsage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_read_tokens=cache_read,
+        cache_write_tokens=cache_write,
+    )

routstr/proxy.py

@@ -24,6 +24,7 @@ from .payment.helpers import (
     calculate_discounted_max_cost,
     check_token_balance,
     create_error_response,
+    create_upstream_error_response,
     get_max_cost_for_model,
 )
 from .payment.models import Model
@@ -211,9 +212,7 @@ async def proxy(
                     e,
                 )
                 if i == len(all_upstreams) - 1:
-                    last_error_response = create_error_response(
-                        "upstream_error", str(e), 502, request=request
-                    )
+                    last_error_response = create_upstream_error_response(e, request)
                 continue
         return last_error_response or create_error_response(
             "upstream_error", "All upstreams failed", 502, request=request
@@ -283,11 +282,10 @@ async def proxy(
                     last_error = e
                 continue
 
+        if last_error is not None:
+            return create_upstream_error_response(last_error, request)
         return create_error_response(
-            "upstream_error",
-            str(last_error) if last_error else "All upstreams failed",
-            502,
-            request=request,
+            "upstream_error", "All upstreams failed", 502, request=request
         )
 
     elif auth := headers.get("authorization", None):
@@ -343,9 +341,7 @@ async def proxy(
             except UpstreamError as e:
                 logger.warning(f"Upstream {upstream.provider_type} failed (GET): {e}")
                 if i == len(upstreams) - 1:
-                    last_error_response = create_error_response(
-                        "upstream_error", str(e), 502, request=request
-                    )
+                    last_error_response = create_upstream_error_response(e, request)
                 continue
         return last_error_response or create_error_response(
             "upstream_error", "All upstreams failed", 502, request=request
@@ -525,9 +521,7 @@ async def proxy(
             # If this was the last provider
             if i == len(upstreams) - 1:
                 await revert_pay_for_request(key, session, max_cost_for_model)
-                return create_error_response(
-                    "upstream_error", str(e), 502, request=request
-                )
+                return create_upstream_error_response(e, request)
 
             # Otherwise loop continues to next provider
             continue

routstr/upstream/base.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import math
 import traceback
 import uuid
 from collections.abc import AsyncGenerator, AsyncIterator, Iterator
@@ -23,6 +24,7 @@ from ..core.db import (
     store_cashu_transaction,
 )
 from ..core.exceptions import UpstreamError
+from ..core.redaction import redact_org_ids
 from ..payment.cost_calculation import (
     CostData,
     CostDataError,
@@ -35,13 +37,19 @@ from ..payment.models import (
     Pricing,
     _calculate_usd_max_costs,
     _update_model_sats_pricing,
+    backfill_cache_pricing,
     list_models,
 )
 from ..payment.price import sats_usd_price
 from ..wallet import recieve_token, send_token
 from . import messages_dispatch
+from .cache_breakpoints import (
+    inject_anthropic_cache_breakpoints,
+    is_explicit_cache_model,
+)
 from .count_tokens import count_tokens_locally
 from .litellm_routing import detect_litellm_prefix
+from .rate_limit import UPSTREAM_RATE_LIMIT, classify_rate_limit
 
 logger = get_logger(__name__)
 
@@ -432,6 +440,19 @@ class BaseUpstreamProvider:
 
         return body
 
+    def _upstream_accepts_cache_control(self) -> bool:
+        """True when this upstream accepts explicit ``cache_control`` markers.
+
+        Only OpenRouter (documents Anthropic + Alibaba explicit caching) and the
+        native Anthropic API accept the markers. Stamping them toward an
+        automatic-cache or non-supporting upstream risks a 400, so injection is
+        confined to these. Base URL is also checked so an OpenRouter endpoint
+        configured through the generic provider is still recognised.
+        """
+        if self.provider_type in ("openrouter", "anthropic"):
+            return True
+        return "openrouter.ai" in (self.base_url or "")
+
     def prepare_request_body(
         self, body: bytes | None, model_obj: Model
     ) -> bytes | None:
@@ -501,6 +522,27 @@ class BaseUpstreamProvider:
                 data["stream_options"] = merged
                 changed = True
 
+        # Explicit-cache models (Anthropic Claude, Alibaba Qwen / deepseek-v3.2)
+        # cache nothing without ``cache_control`` markers in the body. Clients
+        # that don't recognise a routstr URL as one of these never send them, so
+        # caching silently never engages over routstr even though it works
+        # against OpenRouter directly. Stamp the standard breakpoints so caching
+        # works by default, deferring to any client-set markers. Gated to
+        # upstreams that accept the markers (OpenRouter / Anthropic) so they
+        # never leak to an automatic-cache provider that would reject them.
+        if (
+            "messages" in data
+            and isinstance(data.get("messages"), list)
+            and self._upstream_accepts_cache_control()
+            and is_explicit_cache_model(
+                model_obj.id,
+                model_obj.forwarded_model_id,
+                model_obj.canonical_slug,
+            )
+        ):
+            if inject_anthropic_cache_breakpoints(data):
+                changed = True
+
         if changed:
             return json.dumps(data).encode()
         return body
@@ -543,7 +585,7 @@ class BaseUpstreamProvider:
             preview = body_bytes.decode("utf-8", errors="ignore").strip()
             if preview:
                 message = preview[:500]
-        return message, upstream_code
+        return redact_org_ids(message), upstream_code
 
     async def on_upstream_error_redirect(
         self, status_code: int, error_message: str
@@ -586,10 +628,23 @@ class BaseUpstreamProvider:
             body_bytes = b""
             body_read_error = f"{type(exc).__name__}: {exc}"
 
+        # ``message`` is already redacted by ``_extract_upstream_error_message``;
+        # the raw body preview is redacted here before it reaches logs or the
+        # forwarded envelope so provider account identifiers never leak.
         message, upstream_code = self._extract_upstream_error_message(body_bytes)
-        body_preview = body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+        body_preview = redact_org_ids(
+            body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+        )
         is_json_body = _is_json_content_type(content_type)
 
+        # Classify upstream rate-limit failures into a stable, structured error.
+        rate_limit = classify_rate_limit(status_code, message, headers)
+        error_code: str | int = upstream_code or status_code
+        error_details: dict[str, object] | None = None
+        if rate_limit is not None:
+            error_code = UPSTREAM_RATE_LIMIT
+            error_details = rate_limit.as_details()
+
         logger.warning(
             "Upstream %s returned %s for model=%s path=%s: %s",
             self.provider_type,
@@ -603,6 +658,7 @@ class BaseUpstreamProvider:
                 "model": model_id or "unknown",
                 "upstream_status": status_code,
                 "upstream_code": upstream_code,
+                "error_code": error_code,
                 "upstream_content_type": content_type,
                 "upstream_request_id": upstream_request_id,
                 "message_preview": message[:200],
@@ -637,13 +693,41 @@ class BaseUpstreamProvider:
         ):
             headers.pop(header_name, None)
 
+        # Propagate a usable retry hint to the caller when the upstream supplied
+        # one but did not echo a ``Retry-After`` header. RFC 7231 delta-seconds
+        # is an integer, so round sub-second hints up to a usable ``1``.
+        if (
+            rate_limit is not None
+            and rate_limit.retry_after_seconds is not None
+            and "retry-after" not in {k.lower() for k in headers}
+        ):
+            headers["Retry-After"] = str(max(1, math.ceil(rate_limit.retry_after_seconds)))
+
         if is_json_body:
             if not content_type:
                 headers.pop("content-type", None)
                 headers.pop("Content-Type", None)
             media_type = content_type or None
+            # Re-serialise the body with organization IDs stripped. The narrow
+            # ``org-*`` regex preserves the surrounding JSON structure.
+            redacted_text = redact_org_ids(body_bytes.decode("utf-8", errors="ignore"))
+            redacted_body = redacted_text.encode()
+            # Surface the stable rate-limit classification on the forwarded
+            # body so callers can switch on ``error.code`` without parsing the
+            # provider-specific message. Fall back to the redacted bytes if the
+            # body is not a JSON object with an ``error`` mapping.
+            if rate_limit is not None:
+                try:
+                    parsed = json.loads(redacted_text)
+                    err = parsed.get("error") if isinstance(parsed, dict) else None
+                    if isinstance(err, dict):
+                        err["code"] = UPSTREAM_RATE_LIMIT
+                        err["details"] = error_details
+                        redacted_body = json.dumps(parsed).encode()
+                except (ValueError, AttributeError):
+                    pass
             return Response(
-                content=body_bytes,
+                content=redacted_body,
                 status_code=status_code,
                 headers=headers,
                 media_type=media_type,
@@ -654,15 +738,18 @@ class BaseUpstreamProvider:
         for header_name in ("content-type", "Content-Type"):
             headers.pop(header_name, None)
 
+        error_obj: dict[str, object] = {
+            "message": message or "Upstream returned a non-JSON error response",
+            "type": "upstream_error",
+            "code": error_code,
+            "upstream_status": status_code,
+            "upstream_content_type": content_type or None,
+            "upstream_body_preview": body_preview or None,
+        }
+        if error_details is not None:
+            error_obj["details"] = error_details
         envelope = {
-            "error": {
-                "message": message or "Upstream returned a non-JSON error response",
-                "type": "upstream_error",
-                "code": upstream_code or status_code,
-                "upstream_status": status_code,
-                "upstream_content_type": content_type or None,
-                "upstream_body_preview": body_preview or None,
-            },
+            "error": error_obj,
             "request_id": getattr(request.state, "request_id", None),
         }
 
@@ -1018,7 +1105,10 @@ class BaseUpstreamProvider:
                 response_json["id"] = f"chatcmpl-{uuid.uuid4()}"
 
             cost_data = await adjust_payment_for_tokens(
-                key, response_json, session, deducted_max_cost
+                key,
+                response_json,
+                session,
+                deducted_max_cost,
             )
 
             await session.refresh(key)
@@ -1436,7 +1526,10 @@ class BaseUpstreamProvider:
                 response_json["id"] = f"chatcmpl-{uuid.uuid4()}"
 
             cost_data = await adjust_payment_for_tokens(
-                key, response_json, session, deducted_max_cost
+                key,
+                response_json,
+                session,
+                deducted_max_cost,
             )
 
             await session.refresh(key)
@@ -1631,7 +1724,10 @@ class BaseUpstreamProvider:
                             "usage": None,
                         }
                         cost_data = await adjust_payment_for_tokens(
-                            fresh_key, fallback, new_session, max_cost_for_model
+                            fresh_key,
+                            fallback,
+                            new_session,
+                            max_cost_for_model,
                         )
                         usage_finalized = True
                         return f"event: cost\ndata: {json.dumps({'cost': cost_data})}\n\n".encode()
@@ -1850,7 +1946,10 @@ class BaseUpstreamProvider:
                 response_json["usage"] = {"input_tokens": input_tokens}
 
             cost_data = await adjust_payment_for_tokens(
-                key, response_json, session, deducted_max_cost
+                key,
+                response_json,
+                session,
+                deducted_max_cost,
             )
 
             self.inject_cost_metadata(response_json, cost_data, key)
@@ -1952,7 +2051,10 @@ class BaseUpstreamProvider:
             response_json["model"] = requested_model
 
         cost_data = await adjust_payment_for_tokens(
-            key, response_json, session, max_cost_for_model
+            key,
+            response_json,
+            session,
+            max_cost_for_model,
         )
         self.inject_cost_metadata(response_json, cost_data, key)
 
@@ -2440,9 +2542,16 @@ class BaseUpstreamProvider:
                         body_bytes = await response.aread()
                     except Exception:
                         body_bytes = b""
-                    body_preview = body_bytes.decode(
-                        "utf-8", errors="ignore"
-                    ).strip()[:500]
+                    # Redact provider account identifiers before the body text
+                    # reaches logs or the raised error.
+                    body_preview = redact_org_ids(
+                        body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+                    )
+                    rate_limit = classify_rate_limit(
+                        response.status_code,
+                        body_preview,
+                        dict(response.headers),
+                    )
                     logger.error(
                         "Upstream %s returned %s for model=%s path=%s: %s",
                         self.provider_type,
@@ -2454,6 +2563,7 @@ class BaseUpstreamProvider:
                             "provider": self.provider_type,
                             "model": original_model_id or "unknown",
                             "status_code": response.status_code,
+                            "error_code": rate_limit.code if rate_limit else None,
                             "reason_phrase": response.reason_phrase,
                             "path": path,
                             "body_preview": body_preview,
@@ -2466,6 +2576,8 @@ class BaseUpstreamProvider:
                         f"for model {original_model_id or 'unknown'}: "
                         f"{body_preview[:200] or '<empty>'}",
                         status_code=response.status_code,
+                        code=rate_limit.code if rate_limit else None,
+                        details=rate_limit.as_details() if rate_limit else None,
                     )
 
                 try:
@@ -2762,9 +2874,16 @@ class BaseUpstreamProvider:
                         body_bytes = await response.aread()
                     except Exception:
                         body_bytes = b""
-                    body_preview = body_bytes.decode(
-                        "utf-8", errors="ignore"
-                    ).strip()[:500]
+                    # Redact provider account identifiers before the body text
+                    # reaches logs or the raised error.
+                    body_preview = redact_org_ids(
+                        body_bytes.decode("utf-8", errors="ignore").strip()[:500]
+                    )
+                    rate_limit = classify_rate_limit(
+                        response.status_code,
+                        body_preview,
+                        dict(response.headers),
+                    )
                     logger.error(
                         "Upstream %s returned %s for model=%s path=%s: %s",
                         self.provider_type,
@@ -2776,6 +2895,7 @@ class BaseUpstreamProvider:
                             "provider": self.provider_type,
                             "model": original_model_id or "unknown",
                             "status_code": response.status_code,
+                            "error_code": rate_limit.code if rate_limit else None,
                             "path": path,
                             "body_preview": body_preview,
                         },
@@ -2787,6 +2907,8 @@ class BaseUpstreamProvider:
                         f"for model {original_model_id or 'unknown'}: "
                         f"{body_preview[:200] or '<empty>'}",
                         status_code=response.status_code,
+                        code=rate_limit.code if rate_limit else None,
+                        details=rate_limit.as_details() if rate_limit else None,
                     )
 
                 try:
@@ -3025,44 +3147,46 @@ class BaseUpstreamProvider:
             extra={"model": model, "has_usage": "usage" in response_data},
         )
 
-        async with create_session() as session:
-            match await calculate_cost(response_data, max_cost_for_model, session):
-                case MaxCostData() as cost:
-                    logger.debug(
-                        "Using max cost pricing",
-                        extra={"model": model, "max_cost_msats": cost.total_msats},
-                    )
-                    return cost
-                case CostData() as cost:
-                    logger.debug(
-                        "Using token-based pricing",
-                        extra={
-                            "model": model,
-                            "total_cost_msats": cost.total_msats,
-                            "input_msats": cost.input_msats,
-                            "output_msats": cost.output_msats,
-                        },
-                    )
-                    return cost
-                case CostDataError() as error:
-                    logger.error(
-                        "Cost calculation error",
-                        extra={
-                            "model": model,
-                            "error_message": error.message,
-                            "error_code": error.code,
-                        },
-                    )
-                    raise HTTPException(
-                        status_code=400,
-                        detail={
-                            "error": {
-                                "message": error.message,
-                                "type": "invalid_request_error",
-                                "code": error.code,
-                            }
-                        },
-                    )
+        match await calculate_cost(
+            response_data,
+            max_cost_for_model,
+        ):
+            case MaxCostData() as cost:
+                logger.debug(
+                    "Using max cost pricing",
+                    extra={"model": model, "max_cost_msats": cost.total_msats},
+                )
+                return cost
+            case CostData() as cost:
+                logger.debug(
+                    "Using token-based pricing",
+                    extra={
+                        "model": model,
+                        "total_cost_msats": cost.total_msats,
+                        "input_msats": cost.input_msats,
+                        "output_msats": cost.output_msats,
+                    },
+                )
+                return cost
+            case CostDataError() as error:
+                logger.error(
+                    "Cost calculation error",
+                    extra={
+                        "model": model,
+                        "error_message": error.message,
+                        "error_code": error.code,
+                    },
+                )
+                raise HTTPException(
+                    status_code=400,
+                    detail={
+                        "error": {
+                            "message": error.message,
+                            "type": "invalid_request_error",
+                            "code": error.code,
+                        }
+                    },
+                )
         return None
 
     async def send_refund(
@@ -4562,14 +4686,19 @@ class BaseUpstreamProvider:
     def _apply_provider_fee_to_model(self, model: Model) -> Model:
         """Apply provider fee to model's USD pricing and calculate max costs.
 
+        Cache rates missing from the upstream pricing feed are backfilled from
+        litellm's cost map first, so they carry the provider fee like every
+        other price component.
+
         Args:
             model: Model object to update
 
         Returns:
             Model with provider fee applied to pricing and max costs calculated
         """
+        base_pricing = backfill_cache_pricing(model.id, model.pricing)
         adjusted_pricing = Pricing.parse_obj(
-            {k: v * self.provider_fee for k, v in model.pricing.dict().items()}
+            {k: v * self.provider_fee for k, v in base_pricing.dict().items()}
         )
 
         temp_model = Model(

routstr/upstream/cache_breakpoints.py

@@ -0,0 +1,157 @@
+"""Inject explicit prompt-cache breakpoints into OpenAI-shaped requests.
+
+Some upstreams cache *explicitly*: the request must carry
+``cache_control: {"type": "ephemeral"}`` markers on the content blocks that
+should be cached. Two model families use this identical wire format:
+
+* **Anthropic Claude** — direct or via OpenRouter's ``anthropic/*`` models.
+* **Alibaba's explicit-cache models on OpenRouter** — ``qwen/qwen3-max``,
+  ``qwen/qwen-plus``, ``qwen/qwen3.6-plus``, ``qwen/qwen3-coder-plus``,
+  ``qwen/qwen3-coder-flash`` and ``deepseek/deepseek-v3.2`` — which OpenRouter
+  documents as using "the same syntax as Anthropic explicit caching".
+
+Every other provider routstr proxies (OpenAI, Azure, xAI/Grok, Groq, Moonshot,
+default DeepSeek, Gemini implicit, Fireworks) caches *automatically* and needs
+no markers — they are left untouched.
+
+A client that doesn't know it is talking to one of these models *through*
+routstr (e.g. an OpenAI-compatible coding agent pointed at a routstr URL) never
+emits the markers — it only adds them when it recognises the provider as
+OpenRouter. So caching silently never engages over routstr even though the same
+client caches fine talking to OpenRouter directly.
+
+This module restores caching by stamping the standard breakpoints onto the
+forwarded body — the system prompt, the last tool, and the last conversation
+message (the format allows up to four; we use three, matching the common
+agent convention) — but only when the client supplied none of its own, so
+explicit client control always wins. The caller is responsible for only
+applying this toward an upstream that accepts the markers (OpenRouter /
+Anthropic), so they never leak to a provider that would reject them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# The single ephemeral marker stamped onto each chosen breakpoint. A 5-minute
+# TTL (the default for ``ephemeral``) — deliberately not the 1h tier, which
+# carries a higher cache-write premium and should stay opt-in.
+EPHEMERAL_CACHE_CONTROL: dict[str, str] = {"type": "ephemeral"}
+
+# Alibaba's explicit-cache models on OpenRouter. Matched as substrings of the
+# model id (any spelling routstr carries). Snapshot endpoints that OpenRouter
+# documents as *not* supporting explicit caching (e.g. ``qwen3.5-plus-02-15``)
+# are different families and deliberately absent from this list.
+_ALIBABA_EXPLICIT_CACHE_SLUGS: tuple[str, ...] = (
+    "qwen3-max",
+    "qwen-plus",
+    "qwen3.6-plus",
+    "qwen3-coder-plus",
+    "qwen3-coder-flash",
+    "deepseek-v3.2",
+)
+
+
+def is_explicit_cache_model(model_id: str | None, *fallbacks: str | None) -> bool:
+    """True when the target model uses the explicit ``cache_control`` dialect.
+
+    Covers the Claude family (broadly — every Claude model supports it) and
+    Alibaba's documented explicit-cache models, across the id spellings routstr
+    carries: the OpenRouter id (``anthropic/claude-...``, ``qwen/qwen3-max``),
+    the bare upstream id, and any forwarded/canonical alias.
+    """
+    for candidate in (model_id, *fallbacks):
+        if not candidate:
+            continue
+        lowered = candidate.lower()
+        if "claude" in lowered or "anthropic/" in lowered:
+            return True
+        if any(slug in lowered for slug in _ALIBABA_EXPLICIT_CACHE_SLUGS):
+            return True
+    return False
+
+
+def _has_cache_control(obj: Any) -> bool:
+    """Recursively detect any client-supplied ``cache_control`` marker."""
+    if isinstance(obj, dict):
+        if "cache_control" in obj:
+            return True
+        return any(_has_cache_control(v) for v in obj.values())
+    if isinstance(obj, list):
+        return any(_has_cache_control(v) for v in obj)
+    return False
+
+
+def body_has_cache_control(data: dict) -> bool:
+    """True when the request already carries cache_control on messages/tools."""
+    return _has_cache_control(data.get("messages")) or _has_cache_control(
+        data.get("tools")
+    )
+
+
+def _stamp_text_content(message: dict) -> bool:
+    """Add the ephemeral marker to a message's last text block.
+
+    A string content is promoted to the array form Anthropic requires for
+    cache markers; an existing array gets the marker on its last text part.
+    Returns True when a marker was placed.
+    """
+    content = message.get("content")
+    if isinstance(content, str):
+        if not content:
+            return False
+        message["content"] = [
+            {
+                "type": "text",
+                "text": content,
+                "cache_control": dict(EPHEMERAL_CACHE_CONTROL),
+            }
+        ]
+        return True
+    if isinstance(content, list):
+        for part in reversed(content):
+            if isinstance(part, dict) and part.get("type") == "text":
+                part["cache_control"] = dict(EPHEMERAL_CACHE_CONTROL)
+                return True
+    return False
+
+
+def _stamp_system_prompt(messages: list) -> None:
+    for message in messages:
+        if isinstance(message, dict) and message.get("role") in (
+            "system",
+            "developer",
+        ):
+            _stamp_text_content(message)
+            return
+
+
+def _stamp_last_tool(tools: Any) -> None:
+    if isinstance(tools, list) and tools and isinstance(tools[-1], dict):
+        tools[-1]["cache_control"] = dict(EPHEMERAL_CACHE_CONTROL)
+
+
+def _stamp_last_conversation_message(messages: list) -> None:
+    for message in reversed(messages):
+        if isinstance(message, dict) and message.get("role") in ("user", "assistant"):
+            if _stamp_text_content(message):
+                return
+
+
+def inject_anthropic_cache_breakpoints(data: dict) -> bool:
+    """Stamp ephemeral cache breakpoints onto an OpenAI-shaped chat body.
+
+    Mutates ``data`` in place (the established convention in
+    ``prepare_request_body``) and returns True when anything changed. No-ops
+    when the body isn't chat-shaped or the client already set cache_control.
+    """
+    messages = data.get("messages")
+    if not isinstance(messages, list) or not messages:
+        return False
+    if body_has_cache_control(data):
+        return False
+
+    _stamp_system_prompt(messages)
+    _stamp_last_tool(data.get("tools"))
+    _stamp_last_conversation_message(messages)
+    return True

routstr/upstream/messages_dispatch.py

@@ -29,7 +29,9 @@ import litellm
 
 from ..core import get_logger
 from ..core.exceptions import UpstreamError
+from ..core.redaction import redact_org_ids
 from ..payment.models import Model
+from .rate_limit import classify_rate_limit
 
 logger = get_logger(__name__)
 
@@ -505,23 +507,33 @@ async def dispatch_anthropic_messages(
     try:
         result = await litellm.anthropic.messages.acreate(**kwargs)
     except Exception as exc:
-        exc_message = getattr(exc, "message", None) or str(exc) or repr(exc)
+        raw_message = getattr(exc, "message", None) or str(exc) or repr(exc)
+        # Redact provider account identifiers before the message reaches logs
+        # or the surfaced error.
+        exc_message = redact_org_ids(raw_message)
         exc_status = getattr(exc, "status_code", None)
         exc_response = getattr(exc, "response", None)
         response_text = None
         if exc_response is not None:
             try:
-                response_text = getattr(exc_response, "text", str(exc_response))
+                response_text = redact_org_ids(
+                    getattr(exc_response, "text", str(exc_response))
+                )
             except Exception:
                 response_text = "<unreadable>"
+        status_for_classify = exc_status if isinstance(exc_status, int) else 502
+        rate_limit = classify_rate_limit(
+            status_for_classify, exc_message, getattr(exc, "headers", None)
+        )
         logger.error(
             "litellm dispatch failed",
             extra={
                 "error": exc_message,
                 "error_type": type(exc).__name__,
                 "status_code": exc_status,
+                "error_code": rate_limit.code if rate_limit else None,
                 "llm_provider": getattr(exc, "llm_provider", None),
-                "body": getattr(exc, "body", None),
+                "body": redact_org_ids(str(getattr(exc, "body", "") or "")) or None,
                 "response_text": response_text,
                 "model": litellm_model,
                 "api_base": base_url,
@@ -529,7 +541,9 @@ async def dispatch_anthropic_messages(
         )
         raise UpstreamError(
             f"Upstream error via litellm: {exc_message}",
-            status_code=exc_status if isinstance(exc_status, int) else 502,
+            status_code=status_for_classify,
+            code=rate_limit.code if rate_limit else None,
+            details=rate_limit.as_details() if rate_limit else None,
         ) from exc
 
     if not client_stream and hasattr(result, "__aiter__"):

routstr/upstream/rate_limit.py

@@ -0,0 +1,136 @@
+"""Detection and parsing of upstream provider rate-limit errors.
+
+Upstream OpenAI-compatible providers signal rate limits via HTTP 429 and/or a
+human-readable message such as::
+
+    Rate limit reached for gpt-5.5-2026-04-23 (for limit gpt-5.5) in organization
+    org-XXXX on tokens per min (TPM): Limit 180000000, Used 180000000,
+    Requested 8929. Please try again in 2ms.
+
+This module classifies those failures into a stable :data:`UPSTREAM_RATE_LIMIT`
+code and extracts useful debugging fields. All retained text is redacted of
+organization IDs first.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+
+from ..core.redaction import redact_org_ids
+
+# Stable error code callers can switch on to distinguish upstream rate limits
+# from generic request failures. The literal value matches the identifier named
+# in issue #555 ("UPSTREAM_RATE_LIMIT") so the public API contract is exact.
+UPSTREAM_RATE_LIMIT = "UPSTREAM_RATE_LIMIT"
+
+# Message fragments that indicate a rate-limit even when the status code is not
+# 429 (some providers wrap it in a 400/500 envelope).
+_RATE_LIMIT_MARKERS = (
+    "rate limit reached",
+    "rate_limit_exceeded",
+    "rate limit exceeded",
+    "too many requests",
+)
+
+_MODEL_RE = re.compile(r"Rate limit reached for ([^\s(]+)", re.IGNORECASE)
+_LIMIT_NAME_RE = re.compile(r"\(for limit ([^)]+)\)", re.IGNORECASE)
+_METRIC_RE = re.compile(r"on ([a-z ]+\((?:TPM|RPM|TPD|RPD|IPM)\))", re.IGNORECASE)
+_LIMIT_RE = re.compile(r"Limit (\d+)", re.IGNORECASE)
+_USED_RE = re.compile(r"Used (\d+)", re.IGNORECASE)
+_REQUESTED_RE = re.compile(r"Requested (\d+)", re.IGNORECASE)
+_RETRY_RE = re.compile(r"try again in ([\d.]+)\s*(ms|s)", re.IGNORECASE)
+
+
+@dataclass
+class RateLimitInfo:
+    """Structured, redaction-safe view of an upstream rate-limit error."""
+
+    code: str
+    message: str
+    model: str | None = None
+    limit_name: str | None = None
+    metric: str | None = None
+    limit: int | None = None
+    used: int | None = None
+    requested: int | None = None
+    retry_after_seconds: float | None = None
+
+    def as_details(self) -> dict[str, object]:
+        """Return a JSON-serialisable dict for embedding in an error envelope."""
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+def _looks_like_rate_limit(status_code: int, message: str) -> bool:
+    if status_code == 429:
+        return True
+    lowered = message.lower()
+    return any(marker in lowered for marker in _RATE_LIMIT_MARKERS)
+
+
+def _parse_retry_after_header(headers: dict[str, str] | None) -> float | None:
+    """Parse a ``Retry-After`` header (delta-seconds form) into seconds."""
+    if not headers:
+        return None
+    raw = headers.get("retry-after") or headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return float(str(raw).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _int_or_none(match: re.Match[str] | None) -> int | None:
+    if match is None:
+        return None
+    try:
+        return int(match.group(1))
+    except (TypeError, ValueError):
+        return None
+
+
+def classify_rate_limit(
+    status_code: int,
+    message: str,
+    headers: dict[str, str] | None = None,
+) -> RateLimitInfo | None:
+    """Classify an upstream error as a rate-limit and extract its fields.
+
+    Args:
+        status_code: HTTP status code from the upstream response.
+        message: Upstream error message (may contain sensitive identifiers).
+        headers: Optional upstream response headers, used for ``Retry-After``.
+
+    Returns:
+        A :class:`RateLimitInfo` when the error is a rate-limit, else ``None``.
+    """
+    message = message or ""
+    if not _looks_like_rate_limit(status_code, message):
+        return None
+
+    redacted = redact_org_ids(message)
+
+    model_match = _MODEL_RE.search(redacted)
+    metric_match = _METRIC_RE.search(redacted)
+
+    retry_after = _parse_retry_after_header(headers)
+    if retry_after is None:
+        retry_match = _RETRY_RE.search(redacted)
+        if retry_match is not None:
+            value = float(retry_match.group(1))
+            retry_after = value / 1000.0 if retry_match.group(2).lower() == "ms" else value
+
+    limit_name_match = _LIMIT_NAME_RE.search(redacted)
+
+    return RateLimitInfo(
+        code=UPSTREAM_RATE_LIMIT,
+        message=redacted,
+        model=model_match.group(1) if model_match else None,
+        limit_name=limit_name_match.group(1).strip() if limit_name_match else None,
+        metric=metric_match.group(1).strip() if metric_match else None,
+        limit=_int_or_none(_LIMIT_RE.search(redacted)),
+        used=_int_or_none(_USED_RE.search(redacted)),
+        requested=_int_or_none(_REQUESTED_RE.search(redacted)),
+        retry_after_seconds=retry_after,
+    )

routstr/wallet.py

@@ -580,11 +580,19 @@ async def fetch_all_balances(
             }
             return error_result
 
+    # Build the set of mints to inspect. Received tokens are stored against
+    # ``primary_mint`` (which defaults to a real mint even when ``cashu_mints``
+    # is empty), so include it as a fallback — otherwise a node that accepts
+    # payments would still report empty balances when ``cashu_mints`` is unset.
+    mint_urls: list[str] = list(settings.cashu_mints)
+    if settings.primary_mint and settings.primary_mint not in mint_urls:
+        mint_urls.append(settings.primary_mint)
+
     # Create tasks for all mint/unit combinations
     async with db.create_session() as session:
         tasks = [
             fetch_balance(session, mint_url, unit)
-            for mint_url in settings.cashu_mints
+            for mint_url in mint_urls
             for unit in units
         ]
 

tests/unit/test_cache_breakpoints.py

@@ -0,0 +1,189 @@
+"""Tests for Anthropic cache-breakpoint injection on forwarded requests.
+
+Anthropic prompt caching is explicit; a client that doesn't recognise a routstr
+URL as Anthropic-backed never sends ``cache_control`` markers, so caching never
+engages over routstr. ``prepare_request_body`` must stamp the standard
+breakpoints for Anthropic-family models while always deferring to client-set
+markers and never touching automatic-cache providers.
+"""
+
+import json
+import os
+
+import pytest
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+os.environ.setdefault("LIGHTNING_ADDRESS", "test@stm.to")
+
+from routstr.upstream import GenericUpstreamProvider
+from routstr.upstream.cache_breakpoints import (
+    body_has_cache_control,
+    inject_anthropic_cache_breakpoints,
+    is_explicit_cache_model,
+)
+
+
+def _chat_body() -> dict:
+    return {
+        "model": "anthropic/claude-sonnet-4.5",
+        "stream": True,
+        "messages": [
+            {"role": "system", "content": "You are concise."},
+            {"role": "user", "content": "Hello"},
+        ],
+        "tools": [
+            {"type": "function", "function": {"name": "a"}},
+            {"type": "function", "function": {"name": "b"}},
+        ],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Model detection
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "model_id,expected",
+    [
+        ("anthropic/claude-sonnet-4.5", True),
+        ("claude-haiku-4-5-20251001", True),
+        # Alibaba explicit-cache models share Anthropic's wire format
+        ("qwen/qwen3-max", True),
+        ("qwen/qwen3-coder-plus", True),
+        ("deepseek/deepseek-v3.2", True),
+        # Automatic-cache providers need no markers
+        ("openai/gpt-4o", False),
+        ("google/gemini-2.5-flash", False),
+        ("deepseek/deepseek-chat", False),
+        ("qwen/qwen3.5-plus-02-15", False),  # snapshot, no explicit caching
+        (None, False),
+    ],
+)
+def test_is_explicit_cache_model(model_id: str | None, expected: bool) -> None:
+    assert is_explicit_cache_model(model_id) is expected
+
+
+def test_is_explicit_cache_model_uses_fallbacks() -> None:
+    # routstr id is opaque but a forwarded/canonical alias reveals the family.
+    assert is_explicit_cache_model("model-xyz", None, "anthropic/claude-opus-4.1")
+
+
+# ---------------------------------------------------------------------------
+# Breakpoint placement
+# ---------------------------------------------------------------------------
+
+
+def test_injects_three_breakpoints() -> None:
+    data = _chat_body()
+    assert inject_anthropic_cache_breakpoints(data) is True
+
+    # system prompt promoted to array form with a marker
+    system = data["messages"][0]["content"]
+    assert system == [
+        {
+            "type": "text",
+            "text": "You are concise.",
+            "cache_control": {"type": "ephemeral"},
+        }
+    ]
+    # last tool marked
+    assert data["tools"][-1]["cache_control"] == {"type": "ephemeral"}
+    assert "cache_control" not in data["tools"][0]
+    # last user message marked
+    user = data["messages"][1]["content"]
+    assert user[-1]["cache_control"] == {"type": "ephemeral"}
+
+
+def test_defers_to_client_supplied_cache_control() -> None:
+    data = _chat_body()
+    data["messages"][1]["content"] = [
+        {"type": "text", "text": "Hello", "cache_control": {"type": "ephemeral"}}
+    ]
+    assert body_has_cache_control(data) is True
+    # No additional stamping when the client already controls caching.
+    assert inject_anthropic_cache_breakpoints(data) is False
+    assert "cache_control" not in data["tools"][-1]
+
+
+def test_marks_last_text_part_of_array_content() -> None:
+    data = _chat_body()
+    data["messages"][1]["content"] = [
+        {"type": "text", "text": "first"},
+        {"type": "image_url", "image_url": {"url": "x"}},
+        {"type": "text", "text": "last"},
+    ]
+    inject_anthropic_cache_breakpoints(data)
+    parts = data["messages"][1]["content"]
+    assert parts[2]["cache_control"] == {"type": "ephemeral"}
+    assert "cache_control" not in parts[0]
+
+
+def test_noop_without_messages() -> None:
+    assert inject_anthropic_cache_breakpoints({"prompt": "x"}) is False
+
+
+# ---------------------------------------------------------------------------
+# prepare_request_body integration
+# ---------------------------------------------------------------------------
+
+
+def _model(model_id: str):  # type: ignore[no-untyped-def]
+    from routstr.payment.models import Architecture, Model, Pricing
+
+    return Model(
+        id=model_id,
+        name=model_id,
+        created=0,
+        description="",
+        context_length=200000,
+        architecture=Architecture(
+            modality="text->text",
+            input_modalities=["text"],
+            output_modalities=["text"],
+            tokenizer="Claude",
+            instruct_type=None,
+        ),
+        pricing=Pricing(prompt=0.0, completion=0.0),
+    )
+
+
+def _openrouter_provider() -> "GenericUpstreamProvider":
+    # OpenRouter endpoint via the generic provider — recognised by base URL.
+    return GenericUpstreamProvider(base_url="https://openrouter.ai/api/v1")
+
+
+@pytest.mark.parametrize(
+    "model_id", ["anthropic/claude-sonnet-4.5", "qwen/qwen3-max", "deepseek/deepseek-v3.2"]
+)
+def test_prepare_request_body_injects_for_explicit_models(model_id: str) -> None:
+    provider = _openrouter_provider()
+    body = json.dumps(_chat_body()).encode()
+    out = provider.prepare_request_body(body, _model(model_id))
+    assert out is not None
+    data = json.loads(out)
+    assert body_has_cache_control(data) is True
+    assert data["tools"][-1]["cache_control"] == {"type": "ephemeral"}
+
+
+def test_prepare_request_body_skips_for_automatic_provider_model() -> None:
+    provider = _openrouter_provider()
+    body = json.dumps(_chat_body()).encode()
+    out = provider.prepare_request_body(body, _model("openai/gpt-4o"))
+    assert out is not None
+    data = json.loads(out)
+    assert body_has_cache_control(data) is False
+
+
+def test_prepare_request_body_skips_when_upstream_rejects_markers() -> None:
+    # Claude id but a non-OpenRouter/Anthropic upstream → must NOT inject,
+    # since the markers could be rejected by an upstream that doesn't accept them.
+    from routstr.upstream import GenericUpstreamProvider
+
+    provider = GenericUpstreamProvider(base_url="https://some-gateway.example/v1")
+    body = json.dumps(_chat_body()).encode()
+    out = provider.prepare_request_body(body, _model("anthropic/claude-sonnet-4.5"))
+    assert out is not None
+    data = json.loads(out)
+    assert body_has_cache_control(data) is False

tests/unit/test_cache_pricing.py

@@ -0,0 +1,241 @@
+"""Tests for cache-aware pricing of cached input tokens.
+
+Specifies two things:
+
+1. ``backfill_cache_pricing`` — when the OpenRouter model feed omits cache
+   rates (it does for most DeepSeek models and e.g. openai/gpt-4o), they are
+   filled from litellm's bundled cost map instead of silently billing cache
+   reads at the full input rate. Existing OpenRouter values are never
+   overwritten, and provider fees apply to backfilled rates like any other.
+2. ``calculate_cost`` — cached tokens are billed at the cache rates from the
+   model's sats_pricing; the full input rate remains only as the documented
+   last resort when no cache rate could be resolved anywhere.
+"""
+
+import os
+from unittest.mock import Mock, patch
+
+import litellm
+import pytest
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+os.environ.setdefault("LIGHTNING_ADDRESS", "test@stm.to")
+
+from routstr.core.settings import settings
+from routstr.payment.cost_calculation import CostData, calculate_cost
+from routstr.payment.models import (
+    Architecture,
+    Model,
+    Pricing,
+    backfill_cache_pricing,
+)
+from routstr.upstream import GenericUpstreamProvider
+
+
+def _make_model(model_id: str, pricing: Pricing) -> Model:
+    return Model(
+        id=model_id,
+        name=model_id,
+        created=0,
+        description="",
+        context_length=64000,
+        architecture=Architecture(
+            modality="text->text",
+            input_modalities=["text"],
+            output_modalities=["text"],
+            tokenizer="Other",
+            instruct_type=None,
+        ),
+        pricing=pricing,
+    )
+
+
+# ============================================================================
+# backfill_cache_pricing — litellm as fallback source for missing cache rates
+# ============================================================================
+
+
+def test_backfill_deepseek_cache_read_from_litellm() -> None:
+    """deepseek/deepseek-chat has no input_cache_read on OpenRouter; litellm
+    knows the real rate (10x cheaper than input)."""
+    pricing = Pricing(prompt=2.8e-07, completion=4.2e-07)
+
+    result = backfill_cache_pricing("deepseek/deepseek-chat", pricing)
+
+    expected = litellm.model_cost["deepseek/deepseek-chat"][
+        "cache_read_input_token_cost"
+    ]
+    assert result.input_cache_read == expected
+    assert result.input_cache_read < pricing.prompt  # sanity: it's a discount
+
+
+def test_backfill_strips_vendor_prefix_for_litellm_lookup() -> None:
+    """OpenRouter ids are vendor-prefixed (openai/gpt-4o); litellm keys most
+    non-DeepSeek models without the prefix (gpt-4o)."""
+    pricing = Pricing(prompt=2.5e-06, completion=1e-05)
+
+    result = backfill_cache_pricing("openai/gpt-4o", pricing)
+
+    expected = litellm.model_cost["gpt-4o"]["cache_read_input_token_cost"]
+    assert result.input_cache_read == expected
+
+
+def test_backfill_fills_cache_write_rate() -> None:
+    """Anthropic cache writes cost more than input (1.25x); billing them at
+    the input rate undercharges. litellm carries the write rate."""
+    pricing = Pricing(prompt=3e-06, completion=1.5e-05)
+
+    result = backfill_cache_pricing("anthropic/claude-sonnet-4-5", pricing)
+
+    expected = litellm.model_cost["claude-sonnet-4-5"][
+        "cache_creation_input_token_cost"
+    ]
+    assert result.input_cache_write == expected
+    assert result.input_cache_write > pricing.prompt  # sanity: write premium
+
+
+def test_backfill_never_overwrites_openrouter_rates() -> None:
+    """When OpenRouter provides a cache rate, it is authoritative."""
+    pricing = Pricing(
+        prompt=2.1e-07, completion=7.9e-07, input_cache_read=1.3e-07
+    )
+
+    result = backfill_cache_pricing("deepseek/deepseek-chat", pricing)
+
+    assert result.input_cache_read == 1.3e-07
+
+
+def test_backfill_unknown_model_unchanged() -> None:
+    """Models litellm doesn't know stay untouched (last-resort fallback to
+    the input rate happens later, at billing time)."""
+    pricing = Pricing(prompt=1e-06, completion=2e-06)
+
+    result = backfill_cache_pricing("artificial-dumbness/dumb-1", pricing)
+
+    assert result.input_cache_read == 0.0
+    assert result.input_cache_write == 0.0
+
+
+def test_provider_fee_applies_to_backfilled_cache_rates() -> None:
+    """Backfill happens before the provider fee, so cache rates carry the
+    same markup as every other price component."""
+    provider = GenericUpstreamProvider(
+        base_url="http://upstream.example", provider_fee=2.0
+    )
+    model = _make_model(
+        "deepseek/deepseek-chat", Pricing(prompt=2.8e-07, completion=4.2e-07)
+    )
+
+    adjusted = provider._apply_provider_fee_to_model(model)
+
+    litellm_read = litellm.model_cost["deepseek/deepseek-chat"][
+        "cache_read_input_token_cost"
+    ]
+    assert adjusted.pricing.input_cache_read == pytest.approx(litellm_read * 2.0)
+    assert adjusted.pricing.prompt == pytest.approx(2.8e-07 * 2.0)
+
+
+# ============================================================================
+# calculate_cost — cached tokens billed at cache rates
+# ============================================================================
+
+
+@pytest.fixture(autouse=True)
+def patch_sats_usd_price() -> None:  # type: ignore[misc]
+    with patch("routstr.payment.cost_calculation.sats_usd_price", return_value=5.0e-5):
+        yield
+
+
+@pytest.fixture
+def model_pricing(monkeypatch: pytest.MonkeyPatch) -> Mock:
+    """Model-based pricing: 1 msat per input token, 2 per output token,
+    0.1 per cache-read token, 1.25 per cache-write token."""
+    monkeypatch.setattr(settings, "fixed_pricing", False)
+    model = Mock()
+    model.sats_pricing = Pricing(
+        prompt=0.001,
+        completion=0.002,
+        input_cache_read=0.0001,
+        input_cache_write=0.00125,
+    )
+    return model
+
+
+@pytest.mark.asyncio
+async def test_deepseek_cache_hits_billed_at_cache_rate(model_pricing: Mock) -> None:
+    """The reported overcharge scenario: a 10k-token prompt with 90% cache
+    hits costs 2900 msats at honest rates, not the 11000 msats that billing
+    every prompt token at the full input rate would charge."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 10000,
+            "completion_tokens": 500,
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+
+    with patch("routstr.proxy.get_model_instance", return_value=model_pricing):
+        result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # 1000 input @ 1 msat + 9000 cache reads @ 0.1 msat + 500 output @ 2 msat
+    assert result.input_msats == 1000
+    assert result.cache_read_msats == 900
+    assert result.output_msats == 1000
+    assert result.total_msats == 2900
+
+
+@pytest.mark.asyncio
+async def test_anthropic_cache_write_billed_at_write_rate(model_pricing: Mock) -> None:
+    """Cache writes carry their premium rate (1.25x input here), instead of
+    being silently billed at the plain input rate."""
+    response = {
+        "model": "claude-sonnet-4-5",
+        "usage": {
+            "input_tokens": 300,
+            "output_tokens": 100,
+            "cache_read_input_tokens": 500,
+            "cache_creation_input_tokens": 2000,
+        },
+    }
+
+    with patch("routstr.proxy.get_model_instance", return_value=model_pricing):
+        result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # 300 @ 1 + 500 @ 0.1 + 2000 @ 1.25 + 100 @ 2
+    assert result.cache_read_msats == 50
+    assert result.cache_creation_msats == 2500
+    assert result.total_msats == 3050
+
+
+@pytest.mark.asyncio
+async def test_missing_cache_rate_falls_back_to_input_rate(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Documented last resort: when no cache rate could be resolved anywhere
+    (OpenRouter and litellm both silent), cache reads bill at the input rate —
+    never cheaper, never free."""
+    monkeypatch.setattr(settings, "fixed_pricing", False)
+    model = Mock()
+    model.sats_pricing = Pricing(prompt=0.001, completion=0.002)
+
+    response = {
+        "model": "dumb-1",
+        "usage": {
+            "prompt_tokens": 10000,
+            "completion_tokens": 500,
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+
+    with patch("routstr.proxy.get_model_instance", return_value=model):
+        result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # 1000 @ 1 + 9000 @ 1 (fallback) + 500 @ 2
+    assert result.total_msats == 11000

tests/unit/test_cost_calculation_caching.py

@@ -1,10 +1,11 @@
 """Tests for cache token handling in cost calculation.
 
-Covers OpenAI vs Anthropic caching formats, edge cases, and billing accuracy.
+Covers OpenAI, Anthropic and DeepSeek caching formats, dialect precedence,
+edge cases, and billing accuracy.
 """
 
 import os
-from unittest.mock import AsyncMock, patch
+from unittest.mock import patch
 
 import pytest
 
@@ -16,12 +17,6 @@ from routstr.core.settings import settings
 from routstr.payment.cost_calculation import CostData, MaxCostData, calculate_cost
 
 
-@pytest.fixture
-def mock_session() -> AsyncMock:
-    """Mock AsyncSession for cost calculation tests."""
-    return AsyncMock()
-
-
 @pytest.fixture(autouse=True)
 def mock_fixed_pricing(monkeypatch: pytest.MonkeyPatch) -> None:
     """Mock settings and price to use fixed pricing."""
@@ -41,7 +36,7 @@ def patch_sats_usd_price() -> None:  # type: ignore[misc]
 # Test 1: OpenAI Cache Format
 # ============================================================================
 @pytest.mark.asyncio
-async def test_openai_cache_subtraction(mock_session: AsyncMock) -> None:
+async def test_openai_cache_subtraction() -> None:
     """OpenAI includes cached_tokens in prompt_tokens, subtract them."""
     response = {
         "model": "gpt-4",
@@ -53,7 +48,7 @@ async def test_openai_cache_subtraction(mock_session: AsyncMock) -> None:
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 1000  # 2000 - 1000
@@ -65,7 +60,7 @@ async def test_openai_cache_subtraction(mock_session: AsyncMock) -> None:
 # Test 2: Anthropic Cache Format
 # ============================================================================
 @pytest.mark.asyncio
-async def test_anthropic_cache_additive(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_anthropic_cache_additive(mock_fixed_pricing: None) -> None:
     """Anthropic cache tokens are separate (additive) from input_tokens."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -76,7 +71,7 @@ async def test_anthropic_cache_additive(mock_session: AsyncMock, mock_fixed_pric
             "cache_read_input_tokens": 0,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 500
@@ -89,7 +84,7 @@ async def test_anthropic_cache_additive(mock_session: AsyncMock, mock_fixed_pric
 # Test 3: Invalid Cache (Edge Case)
 # ============================================================================
 @pytest.mark.asyncio
-async def test_cache_read_exceeds_prompt_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_cache_read_exceeds_prompt_tokens(mock_fixed_pricing: None) -> None:
     """Handle buggy upstream reporting cached > prompt_tokens."""
     response = {
         "model": "gpt-4",
@@ -101,7 +96,7 @@ async def test_cache_read_exceeds_prompt_tokens(mock_session: AsyncMock, mock_fi
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     # Should not go negative
     assert isinstance(result, CostData)
@@ -114,7 +109,7 @@ async def test_cache_read_exceeds_prompt_tokens(mock_session: AsyncMock, mock_fi
 # Test 4: Malformed Token Values
 # ============================================================================
 @pytest.mark.asyncio
-async def test_malformed_cache_tokens_coerce_to_zero(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_malformed_cache_tokens_coerce_to_zero(mock_fixed_pricing: None) -> None:
     """Handle non-numeric cache token values."""
     response = {
         "model": "gpt-4",
@@ -127,7 +122,7 @@ async def test_malformed_cache_tokens_coerce_to_zero(mock_session: AsyncMock, mo
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     # Both should coerce to 0
     assert isinstance(result, CostData)
@@ -139,7 +134,7 @@ async def test_malformed_cache_tokens_coerce_to_zero(mock_session: AsyncMock, mo
 # Test 5: Anthropic Cache Not Subtracted
 # ============================================================================
 @pytest.mark.asyncio
-async def test_anthropic_cache_not_subtracted(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_anthropic_cache_not_subtracted(mock_fixed_pricing: None) -> None:
     """Anthropic cache fields should NOT be subtracted from input_tokens."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -149,7 +144,7 @@ async def test_anthropic_cache_not_subtracted(mock_session: AsyncMock, mock_fixe
             "cache_read_input_tokens": 200,  # ← Additive, don't subtract
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     # Anthropic: input_tokens stays as-is
     assert isinstance(result, CostData)
@@ -161,7 +156,7 @@ async def test_anthropic_cache_not_subtracted(mock_session: AsyncMock, mock_fixe
 # Test 6: Only Cache Read, No Regular Input
 # ============================================================================
 @pytest.mark.asyncio
-async def test_only_cache_read_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_only_cache_read_tokens(mock_fixed_pricing: None) -> None:
     """Handle response with only cache read tokens."""
     response = {
         "model": "gpt-4",
@@ -173,7 +168,7 @@ async def test_only_cache_read_tokens(mock_session: AsyncMock, mock_fixed_pricin
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 0  # max(0, 0 - 1000)
@@ -185,7 +180,7 @@ async def test_only_cache_read_tokens(mock_session: AsyncMock, mock_fixed_pricin
 # Test 7: Only Cache Creation
 # ============================================================================
 @pytest.mark.asyncio
-async def test_only_cache_creation_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_only_cache_creation_tokens(mock_fixed_pricing: None) -> None:
     """Handle response with only cache creation tokens (Anthropic)."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -196,7 +191,7 @@ async def test_only_cache_creation_tokens(mock_session: AsyncMock, mock_fixed_pr
             "cache_read_input_tokens": 0,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 500
@@ -209,7 +204,7 @@ async def test_only_cache_creation_tokens(mock_session: AsyncMock, mock_fixed_pr
 # Test 8: Both Cache Read and Creation
 # ============================================================================
 @pytest.mark.asyncio
-async def test_both_cache_read_and_creation(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_both_cache_read_and_creation(mock_fixed_pricing: None) -> None:
     """Handle response with both cache read and creation."""
     response = {
         "model": "claude-3-5-sonnet",
@@ -220,7 +215,7 @@ async def test_both_cache_read_and_creation(mock_session: AsyncMock, mock_fixed_
             "cache_read_input_tokens": 500,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 300
@@ -233,7 +228,7 @@ async def test_both_cache_read_and_creation(mock_session: AsyncMock, mock_fixed_
 # Test 9: Token Field Fallback
 # ============================================================================
 @pytest.mark.asyncio
-async def test_token_field_fallback_order(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_token_field_fallback_order(mock_fixed_pricing: None) -> None:
     """Verify fallback order for token extraction."""
     # When prompt_tokens is not present, fall back to input_tokens
     response = {
@@ -243,7 +238,7 @@ async def test_token_field_fallback_order(mock_session: AsyncMock, mock_fixed_pr
             "completion_tokens": 50,
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.input_tokens == 250
@@ -254,20 +249,21 @@ async def test_token_field_fallback_order(mock_session: AsyncMock, mock_fixed_pr
 # Test 10: Float Token Values
 # ============================================================================
 @pytest.mark.asyncio
-async def test_float_token_values_coerced_to_int(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_float_token_values_coerced_to_int(mock_fixed_pricing: None) -> None:
     """Handle float token values by converting to int."""
     response = {
         "model": "gpt-4",
         "usage": {
             "prompt_tokens": 100.7,  # Float
             "completion_tokens": 50.3,  # Float
-            "cache_read_input_tokens": 25.9,  # Float
+            "prompt_tokens_details": {"cached_tokens": 25.9},  # Float
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
-    assert result.input_tokens == 100  # Floored
+    # cached_tokens are part of prompt_tokens (OpenAI dialect) → subtracted: 100 - 25
+    assert result.input_tokens == 75  # Floored
     assert result.output_tokens == 50  # Floored
     assert result.cache_read_input_tokens == 25  # Floored
 
@@ -276,7 +272,7 @@ async def test_float_token_values_coerced_to_int(mock_session: AsyncMock, mock_f
 # Test 11: Boolean Cache Tokens
 # ============================================================================
 @pytest.mark.asyncio
-async def test_boolean_cache_tokens_coerced_to_zero(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_boolean_cache_tokens_coerced_to_zero(mock_fixed_pricing: None) -> None:
     """Handle boolean cache token values by coercing to zero."""
     response = {
         "model": "gpt-4",
@@ -286,7 +282,7 @@ async def test_boolean_cache_tokens_coerced_to_zero(mock_session: AsyncMock, moc
             "cache_read_input_tokens": True,  # Boolean
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.cache_read_input_tokens == 0  # Boolean coerced to 0
@@ -297,7 +293,7 @@ async def test_boolean_cache_tokens_coerced_to_zero(mock_session: AsyncMock, moc
 # Test 12: Zero Cache Tokens
 # ============================================================================
 @pytest.mark.asyncio
-async def test_zero_cache_tokens(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_zero_cache_tokens(mock_fixed_pricing: None) -> None:
     """Handle explicit zero cache tokens."""
     response = {
         "model": "gpt-4",
@@ -309,21 +305,113 @@ async def test_zero_cache_tokens(mock_session: AsyncMock, mock_fixed_pricing: No
             }
         }
     }
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, CostData)
     assert result.cache_read_input_tokens == 0
     assert result.input_tokens == 100
 
 
+# ============================================================================
+# DeepSeek Cache Format
+# DeepSeek emits neither OpenAI's prompt_tokens_details nor Anthropic's
+# cache_read_input_tokens — only prompt_cache_hit_tokens and
+# prompt_cache_miss_tokens, with the documented guarantee
+# prompt_tokens = hit + miss. Hits are ~10x cheaper upstream, so billing
+# them as regular input is a large overcharge.
+# ============================================================================
+@pytest.mark.asyncio
+async def test_deepseek_cache_hit_tokens_extracted() -> None:
+    """DeepSeek cache hits are extracted and removed from regular input.
+
+    Payload shape verbatim from the DeepSeek API reference (usage object).
+    """
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 10000,  # = hit + miss
+            "completion_tokens": 500,
+            "total_tokens": 10500,
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 1000  # only the cache misses
+    assert result.cache_read_input_tokens == 9000
+    assert result.output_tokens == 500
+
+
+@pytest.mark.asyncio
+async def test_deepseek_all_tokens_cached() -> None:
+    """A fully cached DeepSeek prompt bills zero regular input tokens."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 5000,
+            "completion_tokens": 100,
+            "prompt_cache_hit_tokens": 5000,
+            "prompt_cache_miss_tokens": 0,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 0
+    assert result.cache_read_input_tokens == 5000
+
+
+@pytest.mark.asyncio
+async def test_dialect_precedence_never_double_subtracts() -> None:
+    """If a vendor emits both OpenAI-style and DeepSeek-style cache fields for
+    the same cached tokens, they are counted once, not subtracted twice."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 10000,
+            "completion_tokens": 500,
+            "prompt_tokens_details": {"cached_tokens": 9000},
+            "prompt_cache_hit_tokens": 9000,
+            "prompt_cache_miss_tokens": 1000,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 1000  # 10000 - 9000, applied exactly once
+    assert result.cache_read_input_tokens == 9000
+
+
+@pytest.mark.asyncio
+async def test_deepseek_malformed_hit_tokens_coerce_to_zero() -> None:
+    """Malformed DeepSeek cache fields degrade to billing all input at full
+    rate instead of crashing or going negative."""
+    response = {
+        "model": "deepseek-chat",
+        "usage": {
+            "prompt_tokens": 1000,
+            "completion_tokens": 50,
+            "prompt_cache_hit_tokens": "garbage",
+            "prompt_cache_miss_tokens": -5,
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.input_tokens == 1000
+    assert result.cache_read_input_tokens == 0
+
+
 # ============================================================================
 # Test 13: Missing Usage Block
 # ============================================================================
 @pytest.mark.asyncio
-async def test_missing_usage_block(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_missing_usage_block(mock_fixed_pricing: None) -> None:
     """When usage is missing, return MaxCostData with zero tokens."""
     response = {"model": "gpt-4", "choices": [{"message": {"content": "test"}}]}
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, MaxCostData)
     assert result.input_tokens == 0
@@ -335,10 +423,10 @@ async def test_missing_usage_block(mock_session: AsyncMock, mock_fixed_pricing:
 # Test 14: Null Usage Block
 # ============================================================================
 @pytest.mark.asyncio
-async def test_null_usage_block(mock_session: AsyncMock, mock_fixed_pricing: None) -> None:
+async def test_null_usage_block(mock_fixed_pricing: None) -> None:
     """When usage is null, return MaxCostData with zero tokens."""
     response = {"model": "gpt-4", "usage": None}
-    result = await calculate_cost(response, max_cost=100000, session=mock_session)
+    result = await calculate_cost(response, max_cost=100000)
 
     assert isinstance(result, MaxCostData)
     assert result.input_tokens == 0

tests/unit/test_fetch_all_balances.py

@@ -0,0 +1,73 @@
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from routstr.wallet import fetch_all_balances
+
+
+@asynccontextmanager
+async def _fake_session():  # type: ignore[no-untyped-def]
+    yield MagicMock()
+
+
+def _patches(proof_amount: int = 1000):  # type: ignore[no-untyped-def]
+    proof = MagicMock(amount=proof_amount)
+    return [
+        patch("routstr.wallet.get_wallet", AsyncMock(return_value=MagicMock())),
+        patch(
+            "routstr.wallet.get_proofs_per_mint_and_unit",
+            MagicMock(return_value=[proof]),
+        ),
+        patch(
+            "routstr.wallet.slow_filter_spend_proofs",
+            AsyncMock(side_effect=lambda proofs, wallet: proofs),
+        ),
+        patch(
+            "routstr.wallet.db.balances_for_mint_and_unit",
+            AsyncMock(return_value=0),
+        ),
+        patch("routstr.wallet.db.create_session", _fake_session),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_fetch_all_balances_falls_back_to_primary_mint() -> None:
+    """With empty cashu_mints, balances are still fetched for primary_mint."""
+    from routstr.core.settings import settings
+
+    with patch.object(settings, "cashu_mints", []), patch.object(
+        settings, "primary_mint", "http://primary:3338"
+    ):
+        for p in _patches(proof_amount=1000):
+            p.start()
+        try:
+            details, total_wallet, total_user, owner = await fetch_all_balances(
+                units=["sat"]
+            )
+        finally:
+            patch.stopall()
+
+    assert [d["mint_url"] for d in details] == ["http://primary:3338"]
+    assert total_wallet == 1000
+
+
+@pytest.mark.asyncio
+async def test_fetch_all_balances_no_duplicate_primary_mint() -> None:
+    """primary_mint already in cashu_mints is not inspected twice."""
+    from routstr.core.settings import settings
+
+    with patch.object(
+        settings, "cashu_mints", ["http://primary:3338"]
+    ), patch.object(settings, "primary_mint", "http://primary:3338"):
+        for p in _patches(proof_amount=1000):
+            p.start()
+        try:
+            details, total_wallet, _total_user, _owner = await fetch_all_balances(
+                units=["sat"]
+            )
+        finally:
+            patch.stopall()
+
+    assert [d["mint_url"] for d in details] == ["http://primary:3338"]
+    assert total_wallet == 1000

tests/unit/test_messages_litellm_dispatch.py

@@ -500,7 +500,7 @@ async def test_streaming_emits_sse_and_reconciles_cost_at_end() -> None:
     captured_cost_call: dict[str, Any] = {}
 
     async def fake_adjust(
-        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int
+        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int, usage: Any = None
     ) -> dict:
         captured_cost_call["combined_data"] = combined_data
         captured_cost_call["max_cost"] = max_cost
@@ -589,7 +589,7 @@ async def test_streaming_handles_iterator_yielding_raw_sse_bytes() -> None:
     captured: dict[str, Any] = {}
 
     async def fake_adjust(
-        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int
+        fresh_key: Any, combined_data: Any, sess: Any, max_cost: int, usage: Any = None
     ) -> dict:
         captured["combined_data"] = combined_data
         return fake_cost

tests/unit/test_upstream_rate_limit.py

@@ -0,0 +1,396 @@
+"""Tests for upstream rate-limit detection, classification, and org-ID redaction.
+
+Covers issue #555: upstream OpenAI-compatible providers return rate-limit
+errors that embed a sensitive organization ID. The proxy must classify these
+distinctly (``UPSTREAM_RATE_LIMIT``), preserve useful debugging fields, and
+never emit a raw ``org-*`` identifier in logs, errors, or returned bodies.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, Mock, patch
+
+import httpx
+import pytest
+
+from routstr.core.redaction import redact_org_ids
+from routstr.upstream.base import BaseUpstreamProvider
+from routstr.upstream.rate_limit import (
+    UPSTREAM_RATE_LIMIT,
+    RateLimitInfo,
+    classify_rate_limit,
+)
+
+# The exact scenario from the issue, with a realistic (fake) org identifier.
+RAW_ORG_ID = "org-abc123XYZ456def"
+RATE_LIMIT_MESSAGE = (
+    f"Rate limit reached for gpt-5.5-2026-04-23 (for limit gpt-5.5) in "
+    f"organization {RAW_ORG_ID} on tokens per min (TPM): Limit 180000000, "
+    f"Used 180000000, Requested 8929. Please try again in 2ms. Visit "
+    f"https://platform.openai.com/account/rate-limits to learn more."
+)
+
+
+def _make_request(request_id: str = "req-123") -> Mock:
+    request = Mock(spec=["method", "state"])
+    request.method = "POST"
+    request.state = Mock()
+    request.state.request_id = request_id
+    return request
+
+
+def _make_upstream_response(
+    *,
+    body: bytes,
+    status_code: int = 429,
+    content_type: str | None = "application/json",
+    extra_headers: dict[str, str] | None = None,
+) -> httpx.Response:
+    headers: dict[str, str] = {}
+    if content_type is not None:
+        headers["content-type"] = content_type
+    if extra_headers:
+        headers.update(extra_headers)
+    return httpx.Response(status_code=status_code, headers=headers, content=body)
+
+
+@pytest.fixture
+def provider() -> BaseUpstreamProvider:
+    return BaseUpstreamProvider(
+        base_url="https://privateprovider.xyz", api_key="k", provider_fee=1.0
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Redaction
+# --------------------------------------------------------------------------- #
+
+
+def test_redact_org_ids_replaces_identifier() -> None:
+    assert RAW_ORG_ID not in redact_org_ids(RATE_LIMIT_MESSAGE)
+    assert "org-[REDACTED]" in redact_org_ids(RATE_LIMIT_MESSAGE)
+
+
+def test_redact_org_ids_is_idempotent() -> None:
+    once = redact_org_ids(RATE_LIMIT_MESSAGE)
+    assert redact_org_ids(once) == once
+
+
+def test_redact_org_ids_leaves_unrelated_text() -> None:
+    assert redact_org_ids("organize the org-chart") == "organize the org-chart"
+    assert redact_org_ids("") == ""
+
+
+# --------------------------------------------------------------------------- #
+# Classification
+# --------------------------------------------------------------------------- #
+
+
+def test_classify_exact_scenario() -> None:
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE)
+    assert isinstance(info, RateLimitInfo)
+    assert info.code == UPSTREAM_RATE_LIMIT
+    assert info.model == "gpt-5.5-2026-04-23"
+    assert info.limit_name == "gpt-5.5"
+    assert info.metric == "tokens per min (TPM)"
+    assert info.limit == 180000000
+    assert info.used == 180000000
+    assert info.requested == 8929
+    assert info.retry_after_seconds == pytest.approx(0.002)
+    # Redaction-safe: no raw org id survives into the structured view.
+    assert RAW_ORG_ID not in info.message
+    assert RAW_ORG_ID not in json.dumps(info.as_details())
+
+
+def test_classify_by_status_code_without_marker() -> None:
+    info = classify_rate_limit(429, "slow down")
+    assert info is not None
+    assert info.code == UPSTREAM_RATE_LIMIT
+
+
+def test_classify_by_message_marker_without_429() -> None:
+    info = classify_rate_limit(400, "rate_limit_exceeded for this key")
+    assert info is not None
+
+
+def test_retry_after_header_takes_precedence() -> None:
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE, {"Retry-After": "12"})
+    assert info is not None
+    assert info.retry_after_seconds == pytest.approx(12.0)
+
+
+def test_non_rate_limit_error_is_not_classified() -> None:
+    assert classify_rate_limit(400, "invalid request: missing field 'model'") is None
+    assert classify_rate_limit(500, "internal server error") is None
+
+
+# --------------------------------------------------------------------------- #
+# forward_upstream_error_response integration
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_json_rate_limit_body_is_redacted_and_forwarded(
+    provider: BaseUpstreamProvider,
+) -> None:
+    body = json.dumps(
+        {"error": {"message": RATE_LIMIT_MESSAGE, "type": "rate_limit_exceeded"}}
+    ).encode()
+    upstream = _make_upstream_response(body=body, status_code=429)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    assert response.status_code == 429
+    raw = bytes(response.body).decode()
+    # No raw organization id may survive in the forwarded body.
+    assert RAW_ORG_ID not in raw
+    assert "org-[REDACTED]" in raw
+    # Body remains valid JSON; the original type is preserved while a stable
+    # rate-limit code is injected so callers can switch on it.
+    payload: dict[str, Any] = json.loads(raw)
+    assert payload["error"]["type"] == "rate_limit_exceeded"
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["model"] == "gpt-5.5-2026-04-23"
+    # A retry hint extracted from the message is surfaced as a header.
+    assert "retry-after" in {k.lower() for k in response.headers}
+
+
+@pytest.mark.asyncio
+async def test_non_json_rate_limit_envelope_uses_stable_code(
+    provider: BaseUpstreamProvider,
+) -> None:
+    upstream = _make_upstream_response(
+        body=RATE_LIMIT_MESSAGE.encode(),
+        status_code=429,
+        content_type="text/plain",
+    )
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["model"] == "gpt-5.5-2026-04-23"
+    serialized = json.dumps(payload)
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+@pytest.mark.asyncio
+async def test_non_rate_limit_json_error_unchanged(
+    provider: BaseUpstreamProvider,
+) -> None:
+    body = json.dumps(
+        {"error": {"message": "missing field 'model'", "type": "invalid_request"}}
+    ).encode()
+    upstream = _make_upstream_response(body=body, status_code=400)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    assert response.status_code == 400
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "invalid_request"
+    assert "retry-after" not in {k.lower() for k in response.headers}
+
+
+# --------------------------------------------------------------------------- #
+# UpstreamError -> proxy response (preserves code/details/status)
+# --------------------------------------------------------------------------- #
+
+
+def test_create_upstream_error_response_preserves_structure() -> None:
+    from routstr.core.exceptions import UpstreamError
+    from routstr.payment.helpers import create_upstream_error_response
+
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE)
+    assert info is not None
+    err = UpstreamError(
+        f"Upstream error via litellm: {RATE_LIMIT_MESSAGE}",
+        status_code=429,
+        code=info.code,
+        details=info.as_details(),
+    )
+
+    response = create_upstream_error_response(err, _make_request())
+
+    # Original upstream status is preserved (not flattened to 502).
+    assert response.status_code == 429
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["requested"] == 8929
+    serialized = json.dumps(payload)
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+def test_generic_upstream_error_still_defaults_to_502() -> None:
+    from routstr.core.exceptions import UpstreamError
+    from routstr.payment.helpers import create_upstream_error_response
+
+    err = UpstreamError("connection refused")  # status_code defaults to 502
+
+    response = create_upstream_error_response(err, _make_request())
+
+    assert response.status_code == 502
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["code"] == 502
+    assert "details" not in payload["error"]
+
+
+# --------------------------------------------------------------------------- #
+# Structured log-extra redaction
+# --------------------------------------------------------------------------- #
+
+
+def test_security_filter_redacts_org_id_in_extra() -> None:
+    import logging
+
+    from routstr.core.logging import SecurityFilter
+
+    record = logging.LogRecord(
+        name="test",
+        level=logging.ERROR,
+        pathname=__file__,
+        lineno=1,
+        msg="upstream failed",
+        args=(),
+        exc_info=None,
+    )
+    # Simulate an ``extra={"body_preview": ...}`` field carrying an org id.
+    setattr(record, "body_preview", RATE_LIMIT_MESSAGE)
+
+    assert SecurityFilter().filter(record) is True
+    redacted: str = getattr(record, "body_preview")
+    assert RAW_ORG_ID not in redacted
+    assert "org-[REDACTED]" in redacted
+
+
+def test_security_filter_redacts_org_id_in_nested_extra() -> None:
+    import logging
+
+    from routstr.core.logging import SecurityFilter
+
+    record = logging.LogRecord(
+        name="test",
+        level=logging.ERROR,
+        pathname=__file__,
+        lineno=1,
+        msg="upstream failed",
+        args=(),
+        exc_info=None,
+    )
+    # Nested structures: dict containing a list containing the org id.
+    setattr(record, "body", {"error": {"messages": [RATE_LIMIT_MESSAGE]}})
+
+    assert SecurityFilter().filter(record) is True
+    serialized = json.dumps(getattr(record, "body"))
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+# --------------------------------------------------------------------------- #
+# 5xx-wrapped rate limit through forward_upstream_error_response
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_5xx_wrapped_rate_limit_is_classified(
+    provider: BaseUpstreamProvider,
+) -> None:
+    # Some providers wrap a rate-limit in a 5xx envelope; classification must
+    # key off the message marker, not only the 429 status.
+    body = json.dumps({"error": {"message": RATE_LIMIT_MESSAGE}}).encode()
+    upstream = _make_upstream_response(body=body, status_code=500)
+
+    response = await provider.forward_upstream_error_response(
+        _make_request(), "v1/chat/completions", upstream
+    )
+
+    assert response.status_code == 500
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    serialized = json.dumps(payload)
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+
+
+# --------------------------------------------------------------------------- #
+# Real proxy loop: structured error surfaced + reservation reverted once
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_proxy_loop_surfaces_rate_limit_and_reverts_once() -> None:
+    from routstr import proxy as proxy_module
+    from routstr.core.db import ApiKey
+    from routstr.core.exceptions import UpstreamError
+
+    info = classify_rate_limit(429, RATE_LIMIT_MESSAGE)
+    assert info is not None
+
+    key = ApiKey(hashed_key="rlkey", balance=10_000)
+
+    request = MagicMock()
+    request.method = "POST"
+    request.headers = {"authorization": "Bearer sk-rlkey"}
+    request.body = AsyncMock(return_value=b'{"model": "test-model"}')
+    request.state = MagicMock()
+    request.state.request_id = "req-rl"
+
+    upstream = MagicMock()
+    upstream.provider_type = "test"
+    upstream.prepare_headers = MagicMock(side_effect=lambda h: h)
+    upstream.forward_request = AsyncMock(
+        side_effect=UpstreamError(
+            f"Upstream error via litellm: {RATE_LIMIT_MESSAGE}",
+            status_code=429,
+            code=info.code,
+            details=info.as_details(),
+        )
+    )
+
+    session = MagicMock()
+    revert_mock = AsyncMock(return_value=True)
+
+    with (
+        patch.object(proxy_module, "get_model_instance", return_value=MagicMock()),
+        patch.object(proxy_module, "get_provider_for_model", return_value=[upstream]),
+        patch.object(
+            proxy_module, "get_max_cost_for_model", AsyncMock(return_value=1_000)
+        ),
+        patch.object(
+            proxy_module,
+            "calculate_discounted_max_cost",
+            AsyncMock(return_value=1_000),
+        ),
+        patch.object(proxy_module, "check_token_balance", MagicMock()),
+        patch.object(
+            proxy_module, "get_bearer_token_key", AsyncMock(return_value=key)
+        ),
+        patch.object(proxy_module, "pay_for_request", AsyncMock(return_value=1_000)),
+        patch.object(proxy_module, "revert_pay_for_request", revert_mock),
+    ):
+        response = await proxy_module.proxy(
+            request, "v1/chat/completions", session=session
+        )
+
+    # Original 429 status and the stable code/details survive to the client.
+    assert response.status_code == 429
+    payload: dict[str, Any] = json.loads(bytes(response.body))
+    assert payload["error"]["type"] == "upstream_error"
+    assert payload["error"]["code"] == UPSTREAM_RATE_LIMIT
+    assert payload["error"]["details"]["requested"] == 8929
+    serialized = json.dumps(payload)
+    assert RAW_ORG_ID not in serialized
+    assert "org-[REDACTED]" in serialized
+    # Single upstream failed -> reservation reverted exactly once (no double-charge).
+    revert_mock.assert_awaited_once_with(key, session, 1_000)

tests/unit/test_usage_normalization.py

@@ -0,0 +1,140 @@
+"""Tests for vendor-agnostic usage normalization.
+
+Specifies the seam that keeps vendor usage dialects out of generic billing
+code: a canonical ``NormalizedUsage`` shape produced by
+``routstr.payment.usage.normalize_usage`` (union parser for the known,
+non-colliding dialects). ``calculate_cost`` normalizes the response's usage
+object with this parser and needs no vendor knowledge of its own.
+"""
+
+import os
+
+os.environ.setdefault("UPSTREAM_BASE_URL", "http://test")
+os.environ.setdefault("UPSTREAM_API_KEY", "test")
+os.environ.setdefault("LIGHTNING_ADDRESS", "test@stm.to")
+
+import pytest
+
+from routstr.payment.usage import NormalizedUsage, normalize_usage
+
+# ============================================================================
+# The union parser: one canonical shape for all known dialects
+# ============================================================================
+
+
+@pytest.mark.parametrize(
+    "usage,expected",
+    [
+        # OpenAI: cached_tokens included in prompt_tokens → subtracted
+        (
+            {
+                "prompt_tokens": 2000,
+                "completion_tokens": 100,
+                "prompt_tokens_details": {"cached_tokens": 800},
+            },
+            NormalizedUsage(
+                input_tokens=1200,
+                output_tokens=100,
+                cache_read_tokens=800,
+                cache_write_tokens=0,
+            ),
+        ),
+        # DeepSeek: hit/miss fields, prompt_tokens = hit + miss → hit subtracted
+        (
+            {
+                "prompt_tokens": 10000,
+                "completion_tokens": 500,
+                "prompt_cache_hit_tokens": 9000,
+                "prompt_cache_miss_tokens": 1000,
+            },
+            NormalizedUsage(
+                input_tokens=1000,
+                output_tokens=500,
+                cache_read_tokens=9000,
+                cache_write_tokens=0,
+            ),
+        ),
+        # Anthropic: cache fields additive, input_tokens NOT reduced
+        (
+            {
+                "input_tokens": 300,
+                "output_tokens": 100,
+                "cache_read_input_tokens": 500,
+                "cache_creation_input_tokens": 2000,
+            },
+            NormalizedUsage(
+                input_tokens=300,
+                output_tokens=100,
+                cache_read_tokens=500,
+                cache_write_tokens=2000,
+            ),
+        ),
+        # Plain OpenAI without caching
+        (
+            {"prompt_tokens": 100, "completion_tokens": 50},
+            NormalizedUsage(input_tokens=100, output_tokens=50),
+        ),
+        # OpenRouter: cache writes nested as prompt_tokens_details.cache_write_tokens,
+        # both reads and writes included in prompt_tokens → both subtracted
+        (
+            {
+                "prompt_tokens": 10000,
+                "completion_tokens": 60,
+                "prompt_tokens_details": {
+                    "cached_tokens": 5000,
+                    "cache_write_tokens": 2000,
+                },
+            },
+            NormalizedUsage(
+                input_tokens=3000,
+                output_tokens=60,
+                cache_read_tokens=5000,
+                cache_write_tokens=2000,
+            ),
+        ),
+        # litellm-normalized Anthropic: prompt_tokens is the grand total and the
+        # write field is named cache_creation_tokens; top-level fields mirror it.
+        # prompt_tokens present → both subtracted (NOT additive like native).
+        (
+            {
+                "prompt_tokens": 10000,
+                "completion_tokens": 100,
+                "cache_read_input_tokens": 5000,
+                "cache_creation_input_tokens": 2000,
+                "prompt_tokens_details": {
+                    "cached_tokens": 5000,
+                    "cache_creation_tokens": 2000,
+                },
+            },
+            NormalizedUsage(
+                input_tokens=3000,
+                output_tokens=100,
+                cache_read_tokens=5000,
+                cache_write_tokens=2000,
+            ),
+        ),
+    ],
+)
+def test_normalize_usage_dialects(usage: dict, expected: NormalizedUsage) -> None:
+    """Each known vendor dialect maps onto the same canonical shape."""
+    assert normalize_usage(usage) == expected
+
+
+def test_normalize_usage_absent_usage() -> None:
+    """Missing/invalid usage yields None so callers can bill at max cost."""
+    assert normalize_usage(None) is None
+    assert normalize_usage("not a dict") is None  # type: ignore[arg-type]
+
+
+def test_normalize_usage_never_negative() -> None:
+    """Buggy upstreams reporting more cached than prompt tokens clamp to 0."""
+    result = normalize_usage(
+        {
+            "prompt_tokens": 100,
+            "completion_tokens": 50,
+            "prompt_cache_hit_tokens": 150,
+        }
+    )
+    assert result is not None
+    assert result.input_tokens == 0
+    assert result.cache_read_tokens == 150

ui/app/providers/page.tsx

@@ -297,16 +297,13 @@ export default function ProvidersPage() {
   };
 
   const toggleProviderExpansion = (providerId: number) => {
-    const newExpanded = new Set(expandedProviders);
-    if (newExpanded.has(providerId)) {
-      newExpanded.delete(providerId);
-    } else {
-      newExpanded.add(providerId);
-    }
-    setExpandedProviders(newExpanded);
-    if (!newExpanded.has(providerId)) {
+    if (expandedProviders.has(providerId)) {
+      setExpandedProviders(new Set());
       setViewingModels(null);
     } else {
+      // Accordion: only one provider open at a time so switching to another
+      // provider's models auto-collapses the previously expanded one.
+      setExpandedProviders(new Set([providerId]));
       setViewingModels(providerId);
     }
   };