Treat 402 and 403 key-limit errors as one out-of-credits type

Exceeding an OpenRouter API key's credit limit returns 403 "Key limit
exceeded", not 402; 402 is the account running out of credits. The Activity
now raises OpenRouterOutOfCredits for both so the budget gate pauses on either.
Verified live with a key limit set below usage.

Author: DABH

openrouter/README.md

@@ -5,7 +5,7 @@ These samples call [OpenRouter](https://openrouter.ai/) from Temporal Activities
 | Sample | Description |
 |--------|-------------|
 | [prompt_batch](prompt_batch) | Fan one OpenRouter call out per prompt with OpenRouter's Auto Router, and collect answer, model, and cost per prompt. Shows Temporal-owned retries, `Retry-After` handling, and retries served for free from OpenRouter's response cache. Start here. |
-| [budget_gate](budget_gate) | The same batch, but it pauses instead of failing when money runs out, whether a soft budget in the Workflow or OpenRouter's own "insufficient credits" error, and resumes on a `raise_budget` Update. |
+| [budget_gate](budget_gate) | The same batch, but it pauses instead of failing when money runs out, whether a soft budget in the Workflow or OpenRouter refusing the call for lack of credits, and resumes on a `raise_budget` Update. |
 
 For OpenRouter as the model provider behind the [OpenAI Agents SDK plugin](../openai_agents), see [openai_agents/model_providers](../openai_agents/model_providers#openrouter).
 
@@ -50,7 +50,7 @@ uv run --group openrouter openrouter/prompt_batch/run_workflow.py "Explain retri
 [activities.py](activities.py) uses the `openai` SDK pointed at `https://openrouter.ai/api/v1`, which is the setup OpenRouter documents for OpenAI-compatible clients. OpenRouter-specific fields go in `extra_body`. Four things matter for durable execution:
 
 - **Temporal owns retries.** The client is created with `max_retries=0`, so every attempt is one HTTP call and shows up in Event History. If you use OpenRouter's official `openrouter` package instead, pass `retry_config=RetryConfig("none", ...)`: by default it retries 5xx and connection errors for up to an hour, invisibly.
-- **Errors are classified.** 408, 429, and 5xx raise a retryable `ApplicationError`; 400, 401, 402 (out of credits), 403 (moderation), and other 4xx raise a non-retryable one. A `Retry-After` header becomes the next retry delay. OpenRouter can also return HTTP 200 with an `error` body and no `choices`; the Activity checks for that.
+- **Errors are classified.** 408, 429, and 5xx raise a retryable `ApplicationError`; 400, 401, 403 (moderation or permissions), and other 4xx raise a non-retryable one. Running out of money gets its own type, `OpenRouterOutOfCredits`: OpenRouter returns 402 when the account has no credits and 403 `Key limit exceeded` when the API key hit its own credit limit. A `Retry-After` header becomes the next retry delay. OpenRouter can also return HTTP 200 with an `error` body and no `choices`; the Activity checks for that.
 - **Retries are free when the first call succeeded.** The Activity sends `X-OpenRouter-Cache: true`, so if a Worker dies after OpenRouter answered but before Temporal recorded the result, the retried, byte-identical request is served from OpenRouter's response cache and billed at $0. Nothing per-attempt goes in the request body, so attempts stay identical.
 - **Heartbeats.** The Activity heartbeats so a dead Worker is detected after `heartbeat_timeout` (10s) rather than after the full `start_to_close_timeout`.
 

openrouter/activities.py

@@ -44,6 +44,13 @@ def error_type(status: int) -> str:
     return f"OpenRouterHTTP{status}"
 
 
+# Raised instead of an HTTP status type when the call failed for lack of money:
+# 402 when the account is out of credits, or 403 "Key limit exceeded" when the
+# API key hit its own credit limit. A Workflow can pause on this and resume
+# once someone tops up.
+OUT_OF_CREDITS = "OpenRouterOutOfCredits"
+
+
 def _retry_after(headers: Mapping[str, str]) -> Optional[timedelta]:
     value = headers.get("retry-after")
     if value is None:
@@ -60,10 +67,18 @@ def raise_for_status(status: int, message: str, headers: Mapping[str, str]) -> N
 
     Retryable: 408 (timeout), 429 (rate limited, honoring Retry-After), and
     any 5xx (500, 502 model down, 503 no provider available, 524, 529).
-    Non-retryable: other 4xx. 400 is a bad request, 401 a bad key, 402 means
-    the key is out of credits, 403 a moderation or permission block. Retrying
-    those only costs time.
+    Non-retryable: other 4xx. 400 is a bad request, 401 a bad key, 403 a
+    moderation or permission block. Retrying those only costs time.
+    Out of money is its own type (OUT_OF_CREDITS): 402 when the account has no
+    credits, 403 "Key limit exceeded" when the API key hit its credit limit.
     """
+    if status == 402 or (status == 403 and "limit exceeded" in message.lower()):
+        raise ApplicationError(
+            f"OpenRouter returned HTTP {status}: {message}",
+            {"status": status},
+            type=OUT_OF_CREDITS,
+            non_retryable=True,
+        )
     retryable = status in (408, 429) or status >= 500
     raise ApplicationError(
         f"OpenRouter returned HTTP {status}: {message}",

openrouter/budget_gate/README.md

@@ -5,7 +5,7 @@ A prompt batch that pauses instead of failing when money runs out, and resumes w
 ## What this sample demonstrates
 
 - A soft budget enforced by the Workflow from the cost OpenRouter reports on every response. When the next call would exceed it, the batch parks on `workflow.wait_condition` and stays parked for as long as it takes (hours, days) without a Worker doing anything.
-- OpenRouter's own "insufficient credits" error (HTTP 402, raised when the API key hits its credit limit) handled the same way: the failing prompt parks instead of failing, and is re-run after the operator tops up.
+- OpenRouter refusing a call for lack of credits handled the same way: HTTP 402 when the account is out of credits, or HTTP 403 `Key limit exceeded` when the API key hit its own credit limit. The failing prompt parks instead of failing, and is re-run after the operator tops up.
 - A `raise_budget` Update to resume, with a validator that rejects lowering the budget, and a `spend_report` Query showing spend, reservations, the ledger, and which prompts are parked and why.
 - Completed prompts are never re-run. A restarted Worker, or a resumed batch, continues from the first unfinished prompt.
 
@@ -60,21 +60,45 @@ Total cost: $0.000873
 
 ### Out of credits at OpenRouter
 
-Set a credit limit on your API key in the [OpenRouter dashboard](https://openrouter.ai/settings/keys) below what the batch needs, and run with a generous soft budget. When OpenRouter returns 402, the prompt parks with reason `insufficient_credits`. Raise the key's limit, then send `raise_budget` with the current budget value to resume; the parked prompt is re-run.
+Set a credit limit on your API key in the [OpenRouter dashboard](https://openrouter.ai/settings/keys) below what the batch needs, and run with a generous soft budget:
+
+```bash
+uv run --group openrouter openrouter/budget_gate/run_workflow.py --budget-usd 1.0
+```
+
+When OpenRouter refuses the call (`403 Key limit exceeded` for a per-key limit, `402` when the account is out of credits), the prompt parks with reason `insufficient_credits`:
+
+```json
+{
+  "budget_usd": 1,
+  "spent_usd": 0,
+  "completed": 0,
+  "paused": {
+    "Define durable execution in one sentence.": "insufficient_credits",
+    "Why do LLM calls belong in Activities?": "insufficient_credits"
+  }
+}
+```
+
+Raise the key's limit in the dashboard, then send `raise_budget` with the current budget value to resume; the parked prompts are re-run:
+
+```bash
+uv run --group openrouter openrouter/budget_gate/raise_budget.py <workflow-id> 1.0
+```
 
 If nobody raises the budget within `--approval-timeout-seconds` (default one hour), the batch completes with the remaining prompts listed as skipped.
 
 ## What the soft budget does and does not guarantee
 
-The cost of a call is only known after the response, so the Workflow reserves `--estimate-usd` per in-flight call and checks `spent + reserved + estimate <= budget` before starting one. Overshoot is therefore bounded by `max_concurrency * estimate`, plus the gap between the estimate and the real cost of the calls already in flight. In the run above, the second prompt alone cost more than the whole budget; the third prompt is where the gate closed. To bound the cost of a single call, set `provider.max_price` in the request (see OpenRouter's provider routing docs). The hard cap is the credit limit on the OpenRouter API key, which is what produces the 402.
+The cost of a call is only known after the response, so the Workflow reserves `--estimate-usd` per in-flight call and checks `spent + reserved + estimate <= budget` before starting one. Overshoot is therefore bounded by `max_concurrency * estimate`, plus the gap between the estimate and the real cost of the calls already in flight. In the run above, the second prompt alone cost more than the whole budget; the third prompt is where the gate closed. To bound the cost of a single call, set `provider.max_price` in the request (see OpenRouter's provider routing docs). The hard cap is the credit limit on the OpenRouter API key, which is what produces the `403 Key limit exceeded`.
 
 While parked, in-flight prompts keep their concurrency slots and every remaining prompt parks on the same condition, so nothing spends until the budget is raised.
 
 ## Files
 
 | File | Description |
 |------|-------------|
-| [workflow.py](workflow.py) | `BudgetGateWorkflow`: reservation ledger, pause on soft budget or 402, `raise_budget` Update with validator, `spend_report` Query. |
+| [workflow.py](workflow.py) | `BudgetGateWorkflow`: reservation ledger, pause on soft budget or out-of-credits, `raise_budget` Update with validator, `spend_report` Query. |
 | [run_worker.py](run_worker.py) | Builds the OpenRouter client once and runs the Worker. |
 | [run_workflow.py](run_workflow.py) | Starts a batch with a budget and prints the result. |
 | [raise_budget.py](raise_budget.py) | Sends the `raise_budget` Update. |

openrouter/budget_gate/workflow.py

@@ -10,7 +10,7 @@
 # The shared dataclasses are passed through the sandbox so that objects the
 # Activity returns are the same classes the Workflow compares against.
 with workflow.unsafe.imports_passed_through():
-    from openrouter.activities import OpenRouterActivities, error_type
+    from openrouter.activities import OUT_OF_CREDITS, OpenRouterActivities
     from openrouter.shared import (
         MAX_PROMPTS_PER_BATCH,
         BatchResult,
@@ -22,16 +22,17 @@
         SpendReport,
     )
 
-INSUFFICIENT_CREDITS = error_type(402)
+INSUFFICIENT_CREDITS = OUT_OF_CREDITS
 
 
 @workflow.defn
 class BudgetGateWorkflow:
     """A prompt batch that pauses instead of failing when money runs out.
 
     Two things can pause it: the soft budget in the input (checked against the
-    cost OpenRouter reports per response) and OpenRouter itself returning 402
-    because the API key hit its credit limit. Either way the batch parks until
+    cost OpenRouter reports per response) and OpenRouter itself refusing the
+    call for lack of credits (402 for the account, 403 "Key limit exceeded"
+    for the API key). Either way the batch parks until
     a `raise_budget` Update arrives, then resumes exactly where it stopped.
     Completed prompts are never re-run.
     """
@@ -130,7 +131,7 @@ async def _answer(
                             isinstance(cause, ApplicationError)
                             and cause.type == INSUFFICIENT_CREDITS
                         ):
-                            # The API key is out of credits. Park until the
+                            # Out of credits at OpenRouter. Park until the
                             # operator tops up and sends raise_budget.
                             if await self._wait_for_more_credits(prompt, timeout):
                                 continue

tests/openrouter/activity_test.py

@@ -131,11 +131,29 @@ def handler(request: httpx.Request) -> httpx.Response:
             make_activities(handler).call_openrouter, OpenRouterRequest(prompt="hi")
         )
 
-    assert excinfo.value.type == "OpenRouterHTTP402"
+    assert excinfo.value.type == "OpenRouterOutOfCredits"
     assert excinfo.value.non_retryable
     assert "Insufficient credits" in str(excinfo.value)
 
 
+async def test_key_limit_exceeded_is_out_of_credits_too() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            403,
+            json={
+                "error": {"code": 403, "message": "Key limit exceeded (total limit)"}
+            },
+        )
+
+    with pytest.raises(ApplicationError) as excinfo:
+        await ActivityEnvironment().run(
+            make_activities(handler).call_openrouter, OpenRouterRequest(prompt="hi")
+        )
+
+    assert excinfo.value.type == "OpenRouterOutOfCredits"
+    assert excinfo.value.non_retryable
+
+
 async def test_server_error_is_retryable() -> None:
     def handler(request: httpx.Request) -> httpx.Response:
         return httpx.Response(502, json={"error": {"code": 502, "message": "down"}})

tests/openrouter/budget_gate_test.py

@@ -22,7 +22,7 @@
 
 
 class FakeOpenRouter:
-    """Mock Activity with a per-prompt count and an optional 402 on first call."""
+    """Mock Activity with a per-prompt count; optionally out of credits on first call."""
 
     def __init__(self, out_of_credits_for: set[str] | None = None) -> None:
         self.calls: dict[str, int] = {}
@@ -36,8 +36,8 @@ async def call_openrouter(self, request: OpenRouterRequest) -> OpenRouterResult:
             and self.calls[request.prompt] == 1
         ):
             raise ApplicationError(
-                "OpenRouter returned HTTP 402: Insufficient credits",
-                type="OpenRouterHTTP402",
+                "OpenRouter returned HTTP 403: Key limit exceeded (total limit)",
+                type="OpenRouterOutOfCredits",
                 non_retryable=True,
             )
         return OpenRouterResult(