fix: make Retry-After use relative delay and improve 429 UX

[lc0rp]

Impelements

• RFC-compliant Retry-After behavior on 429 (delay-seconds, not UNIX epoch).
• Added standardized RateLimit-* headers while keeping legacy X-RateLimit-*.
• Display retry/budget/reset info and honors Retry-After with jittered backoff in UI
• Docs updates for 429 behavior, examples, and proxy/IP caveats.

Rationale

• Current epoch-based Retry-After is non-standard and can cause immediate re-failure loops. See:
  • Rate limit too aggressive + no visibility (no headers, no docs) #349
  • Rate limit exceeded when installing skills via npx clawhub@latest install <skill>` #390
  • Bug: Retry-After uses absolute Unix epoch on 429, instead of retry delay seconds #407
• UI void of actionable retry guidance beyond "Rate limit exceeded".

Work done

• Updated limiter headers in convex/lib/httpRateLimit.ts.
• Added regression tests in convex/lib/httpRateLimit.test.ts.
• Updated CLI HTTP handling/retry logic in packages/clawdhub/src/http.ts.
• Added/updated CLI tests in packages/clawdhub/src/http.test.ts and packages/clawdhub/src/http.bun.test.ts.
• Updated docs:
  • docs/http-api.md
  • docs/api.md
  • docs/troubleshooting.md
  • docs/deploy.md

Testing

• bun run lint
• bunx vitest run convex/lib/httpRateLimit.test.ts packages/clawdhub/src/http.test.ts packages/clawdhub/src/http.bun.test.ts
• bun run test

Checklist

• Added test coverage and tested
• bun run lint
• Tested and working locally

Worked w/ codex on this.

Fixes #407

Greptile Summary

Standardizes Retry-After header semantics to use RFC-compliant delay-seconds instead of Unix epoch timestamps, and adds standardized RateLimit-* headers alongside legacy X-RateLimit-* headers. The CLI is updated to parse these headers, display actionable retry/budget/reset info in error messages, and honor Retry-After with jittered backoff.

• Server-side (convex/lib/httpRateLimit.ts): now emits both X-RateLimit-Reset (epoch) and RateLimit-Reset (delay), and Retry-After as delay-seconds on 429
• CLI (packages/clawdhub/src/http.ts): replaces inline p-retry with runWithRetries that reads Retry-After, enriches error messages with retry/budget info, and supports legacy epoch-based Retry-After via a >1-year heuristic
• Curl path: updated --write-out format to extract rate-limit headers via a structured metadata marker (__CLAWHUB_CURL_META__)
• Docs: updated api.md, http-api.md, deploy.md, and troubleshooting.md with new header semantics, example 429 responses, client handling guidance, and proxy/IP caveats
• Test coverage added for both server-side header generation and CLI-side header parsing/retry behavior

Confidence Score: 4/5

• This PR is safe to merge with low risk — changes are well-tested and backwards compatible.
• The implementation is solid with good test coverage across both Node and Bun paths. The server-side change is minimal and correct. The CLI-side refactor is larger but well-structured with backward compatibility for old-format curl output and legacy epoch-based Retry-After. One minor style issue (duplicate parseRateLimitInfo calls) has no functional impact.
• packages/clawdhub/src/http.ts has a minor redundancy in error path (double parseRateLimitInfo call) worth cleaning up.

_{Last reviewed commit: d04c1e2}

Context used:

• Context from dashboard - AGENTS.md (source)

[vercel]

@lc0rp is attempting to deploy a commit to the Amantus Machina Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

_{9 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}