[mansur-codes]

feat(api): add Retry-After headers and rate limit documentation to every 429 response (#272)

Summary

• Retry-After & standard rate limit headers: Added numeric Retry-After seconds header along with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to all 429 responses.
• Consistent 429 response body: Standardized rate-limited response body shape to { "code": "rate_limited", "retryAfter": <seconds>, "message": "Rate limit exceeded. Retry after <seconds> seconds." }, ensuring retryAfter matches the Retry-After header value exactly.
• Rate limit documentation: Added a ## Rate Limits section to README.md documenting exact limits per route class (public routes: 100/min per IP, authenticated routes: 60/min per API key, write routes: 10/min per payTo).
• OpenAPI specification: Updated components.responses.TooManyRequests with rate limit headers and response schema. Added 429 response references to all non-exempt routes (/venues/registry, /supported, /verify, /settle, and GET/POST /graphql), while preserving exemption on probe routes (/live, /ready). Regenerated openapi.json.
• Tests: Added tests/rateLimit.test.ts to assert 429 header/body parity, probe route exemptions, and programmatically compare documented README.md limit values against configured values in config.rateLimit.

Related issue

Closes #272

Type of change

• Bug fix
• New feature
• Refactor
• Docs
• Tests
• CI / tooling

Checklist

• I have read CONTRIBUTING.md
• npx tsc --noEmit passes
• npm run build passes
• I added / updated tests where relevant
• I updated docs where relevant

[drips-wave]

@mansur-codes Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits