fix(wallet): return 425 when refund is pending, not 404

The X-Cashu refund endpoint raised 404 "Refund not found" when the
"in" transaction existed with a request_id but the "out" (refund)
transaction had not been written yet. This is a timing race: the
endpoint is polled while the upstream request is still in flight,
before send_refund() has minted and stored the refund token.

The 404 was indistinguishable from a genuinely-missing refund, so
clients had no signal that retrying would succeed — leading to
stranded refunds when clients gave up.

Replace the third 404 branch with 425 Too Early + Retry-After: 2.
The two earlier 404 branches (no "in" row, no request_id) remain 404
since those genuinely mean no refund will ever exist.

Also adds debug logging on all three not-found/pending branches so
the race is no longer invisible to operators (middleware does not log
request headers).

Adds unit tests for the new 425 pending path and the no-request_id
404 path.

Refs: refund-race-condition

routstr/balance.py

@@ -274,7 +274,20 @@ async def refund_wallet_endpoint(
         )
         out_tx = out_tx_result.first()
         if out_tx is None:
-            raise HTTPException(status_code=404, detail="Refund not found")
+            # The "in" row exists with a request_id, but the "out" (refund)
+            # row hasn't been written yet — the upstream request is still in
+            # flight and the refund will be minted once it completes. Tell the
+            # client to retry instead of 404ing permanently (race condition
+            # where /v1/wallet/refund is polled before the refund exists).
+            logger.debug(
+                "refund_wallet_endpoint: refund pending (in row exists, out row not yet created)",
+                extra={"request_id": in_tx.request_id},
+            )
+            raise HTTPException(
+                status_code=425,
+                detail="Refund is pending; retry shortly.",
+                headers={"Retry-After": "2"},
+            )
         if out_tx.swept:
             raise HTTPException(status_code=410, detail="Refund has been swept")
 

tests/unit/test_balance.py

@@ -103,6 +103,64 @@ async def test_refund_x_cashu_not_found_raises_404() -> None:
     assert exc_info.value.status_code == 404
 
 
+@pytest.mark.asyncio
+async def test_refund_x_cashu_pending_raises_425() -> None:
+    """in row exists with a request_id but out row not yet created → 425.
+
+    This is the race condition where /v1/wallet/refund is polled while the
+    upstream request is still in flight. The endpoint must signal "retry"
+    rather than a permanent 404.
+    """
+    from fastapi import HTTPException
+
+    x_cashu_token = "cashuApending_token"
+    in_tx = _make_cashu_tx(
+        token=x_cashu_token, amount=0, unit="msat", type="in", request_id="req-pending"
+    )
+
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_exec_result(in_tx), _exec_result(None)])
+    session.add = MagicMock()
+    session.commit = AsyncMock()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-somekey",
+            x_cashu=x_cashu_token,
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 425
+    assert exc_info.value.headers == {"Retry-After": "2"}
+
+
+@pytest.mark.asyncio
+async def test_refund_x_cashu_in_tx_without_request_id_raises_404() -> None:
+    """in row exists but has no request_id (cannot link to a refund) → 404.
+
+    This is a genuine "no refund will ever exist" case, distinct from the
+    pending 425 path.
+    """
+    from fastapi import HTTPException
+
+    x_cashu_token = "cashuAnoreqid_token"
+    in_tx = _make_cashu_tx(
+        token=x_cashu_token, amount=0, unit="msat", type="in", request_id=None
+    )
+
+    session = MagicMock()
+    session.exec = AsyncMock(side_effect=[_exec_result(in_tx)])
+
+    with pytest.raises(HTTPException) as exc_info:
+        await refund_wallet_endpoint(
+            authorization="Bearer sk-somekey",
+            x_cashu=x_cashu_token,
+            session=session,
+        )
+
+    assert exc_info.value.status_code == 404
+
+
 @pytest.mark.asyncio
 async def test_refund_x_cashu_swept_raises_410() -> None:
     from fastapi import HTTPException