Wave A PR 3: typed errors + 401/429 escalation + body-size + key validation

[AndresL230]

Summary

• Middleware silently drops windows on 401, no escalation path #14 401 escalation: consecutive 401s emit RecostAuthError; the 5th emits RecostFatalAuthError and suspends the transport. First failure also prints a one-line stderr warning so the developer is told immediately.
• Rate-limit 429 is not honored — drop window with no Retry-After, no typed event #18 429 Retry-After: parses the Retry-After header (seconds or HTTP-date), defers the next flush by that delay, emits RecostRateLimitError. Window is not dropped.
• Mode detection is silent — invalid API key auto-enters cloud mode and fails #17 api_key validation: init(api_key="undefined") now raises ValueError with a clear message. Catches the most common misconfig.
• Interceptor body-size measurement: aiohttp json=, httpx streaming, Content-Length only #8 body sizes: aiohttp json= and FormData are now measured; httpx streaming bodies are explicitly skipped to avoid OOM on large uploads.
• README updated to document streaming caveats.

Stacked on PR 2 (#30) and PR 1 (#29) — the diff will resolve as the earlier PRs merge.

Public API additions

• RecostError (PR 2), RecostAuthError, RecostFatalAuthError, RecostRateLimitError — all subclasses of Exception. Existing on_error: Callable[[Exception], None] signature unchanged.

Test plan

• tests/test_errors.py — new exception classes import and carry expected attrs.
• tests/test_transport.py — 401 escalation, fatal at 5, 429 deferral, 429 not auth-counted.
• tests/test_init.py — api_key="undefined" raises.
• tests/test_interceptor.py — aiohttp json=/FormData sized, httpx streaming not materialized.
• CI matrix green.

Closes #8, #14, #17, #18.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@AndresL230 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 34 minutes and 53 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5e433567-4982-4a9b-80fc-b43e79d6e6a7

📥 Commits

Reviewing files that changed from the base of the PR and between edf8b23 and c4f9ba1.

📒 Files selected for processing (24)

• .github/workflows/ci.yml
• README.md
• docs/superpowers/plans/2026-05-13-wave-a-production-readiness.md
• docs/superpowers/specs/2026-05-13-wave-a-production-readiness-design.md
• pyproject.toml
• recost/__init__.py
• recost/_aggregator.py
• recost/_init.py
• recost/_interceptor.py
• recost/_provider_registry.py
• recost/_transport.py
• recost/_types.py
• recost/frameworks/fastapi.py
• recost/frameworks/flask.py
• tests/conftest.py
• tests/test_aggregator.py
• tests/test_errors.py
• tests/test_fastapi.py
• tests/test_fork_safety.py
• tests/test_init.py
• tests/test_interceptor.py
• tests/test_reentrancy.py
• tests/test_scaffold.py
• tests/test_transport.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch wave-a/pr3-transport

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}