feat: add support for Retry-After header on 429 responses

[AryanSharma48]

Description

This PR introduces support for parsing and honoring the Retry-After header when receiving a 429 Too Many Requests response. Previously, the libraries relied solely on the exponential backoff calculation. Now, if the header is present and valid, the client will wait for the exact duration requested by the server before retrying, falling back to the standard backoff if it's missing.

Affected packages and files:

• packages/smooth-api-ts: src/index.ts, tests/resilience.test.ts
• packages/smooth-api-py: smooth_api/__init__.py, tests/test_resilience.py
• README.md: Checked off the "Retry-After header support" task.

Fixes #1

Type of Change

Please check the option that applies:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update (changes to READMEs, docs, or inline comments)

Checklist

Design & Parity

• If this introduces a new configuration option or public API, I have implemented equivalent options/behavior in both TypeScript and Python packages.
• The library remains dependency-free (no new external runtime dependencies added).
• I have updated the relevant package-specific README.md or general documentation where necessary.

Quality & Testing

• I started the sandbox Express server (cd sandbox && node server.js) before running the tests.
• TypeScript Package: I have built and run the TypeScript tests (npm run build && npm test inside packages/smooth-api-ts) and all tests passed.
• Python Package: I have run the Python tests (pytest tests/ inside packages/smooth-api-py) and all tests passed.
• I have added new tests to cover my changes.
• I have commented my code, particularly in hard-to-understand areas, and updated JSDoc/docstrings.

Summary by CodeRabbit

• New Features

  • HTTP 429 retries now respect a valid positive Retry-After header, helping requests resume at the server-recommended time.
  • Supported in both synchronous and asynchronous Python workflows, as well as TypeScript.
  • Automatic backoff remains available when the header is missing or invalid.

• Documentation

  • Updated the roadmap to mark Retry-After support as completed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
smooth-api	Ready	Preview	Aug 11, 2026 1:42pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1e8772ee-21e8-4140-a626-7929dba51164

📥 Commits

Reviewing files that changed from the base of the PR and between e5934ed and 2bc164d.

📒 Files selected for processing (5)

• README.md
• packages/smooth-api-py/smooth_api/__init__.py
• packages/smooth-api-py/tests/test_resilience.py
• packages/smooth-api-ts/src/index.ts
• packages/smooth-api-ts/tests/resilience.test.ts

---

📝 Walkthrough

Walkthrough

The Python and TypeScript clients now honor positive numeric Retry-After headers for HTTP 429 retries. Existing calculated backoff remains the fallback. Synchronous, asynchronous, and TypeScript tests cover the behavior.

Changes

Retry-After support

Layer / File(s)	Summary
Python retry delay handling packages/smooth-api-py/smooth_api/__init__.py, packages/smooth-api-py/tests/test_resilience.py	Python parses positive numeric Retry-After values and applies them to synchronous and asynchronous HTTP 429 retries. Tests verify the delay, retry count, and successful response.
TypeScript retry delay handling and roadmap packages/smooth-api-ts/src/index.ts, packages/smooth-api-ts/tests/resilience.test.ts, README.md	TypeScript converts valid positive Retry-After seconds to milliseconds for HTTP 429 retries. The test verifies delay and retry count. The roadmap marks support as complete.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant API
  participant RetryFlow
  participant Timer
  Client->>API: Send request
  API-->>RetryFlow: Return HTTP 429 with Retry-After
  RetryFlow->>RetryFlow: Parse positive retry delay
  RetryFlow->>Timer: Wait for server-provided delay
  Timer-->>Client: Retry request
  Client->>API: Send retry request
  API-->>Client: Return success response

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/retry-after-support

---

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.}