Author an API rate-limiting and quota reference for integrators in docs/rate-limiting.md

[1nonlypiece]

📌 Description

The backend enforces per-org and per-IP rate-limit tiers, export quotas with 429
enforcement, and emits RateLimit-Limit/Retry-After headers, with a Redis-backed
distributed store for multi-replica deployments. There is no consolidated,
integrator-facing reference describing the limits, headers, and recommended client
backoff behaviour, so consumers cannot build correct retry logic.

This issue authors a rate-limiting and quota reference.

🎯 Requirements and Context

• Document each rate-limit tier and quota (auth, api-keys, jobs, exports, privacy)
  with the limits and windows actually configured.
• Document the response headers (RateLimit-Limit, RateLimit-Remaining,
  Retry-After) and the 429 envelope shape.
• Recommend a client backoff-with-jitter pattern honouring Retry-After.
• Note multi-replica behaviour via the distributed token-bucket store.

🛠️ Suggested Execution

1. Fork the repo and create a branch

git checkout -b docs/rate-limiting-reference

2. Implement changes

• Author docs/rate-limiting.md reflecting src/middleware/rateLimiter.ts and the
  export quota logic.
• Add src/tests/docs.rateLimiting.test.ts asserting documented header names
  match those emitted by the middleware.

3. Test and commit

• Run: npm test -- src/tests/docs.rateLimiting.test.ts
• Cover edge cases: header names match implementation, documented tiers exist,
  429 envelope shape matches the error contract.

Example commit message

docs: integrator rate-limiting and quota reference

✅ Guidelines

• Minimum 95% test coverage on any assertion code added.
• Documented headers/tiers must match the implementation.
• Timeframe: 96 hours.

🏷️ Labels

type-documentation · area-backend · MAYBE REWARDED · GRANTFOX OSS · OFFICIAL CAMPAIGN

💬 Community & Support

• Join the contributor Discord to coordinate, ask questions, and get unblocked fast: https://discord.gg/xvNAvMJf
• Please introduce yourself in the channel before you start so we can avoid duplicate work, pair you with a reviewer, and get your PR merged quickly.
• Maintainers actively triage this channel and aim for fast, clear, respectful reviews — reach out any time you're blocked.

[nelly439]

I'd like to work on this issue.

I have experience writing API documentation and backend tests. I can create a comprehensive rate-limiting reference that accurately reflects the implementation, including all configured rate-limit tiers, export quotas, response headers, 429 error format, recommended client backoff with jitter, and the Redis-backed distributed rate-limiting behavior. I'll also add tests to ensure the documented headers, tiers, and error contract remain synchronized with the middleware so future changes don't cause the documentation to drift.

[Ebenezer199914]

can i work on this issue

[linoxbt]

Hi, I'd like to work on this issue. I have experience with backend APIs, technical documentation, and test-driven maintenance of developer-facing documentation. For this task, I would review the rate-limiting middleware and export quota implementation to produce an accurate integrator reference covering rate-limit tiers, quota behavior, response headers, 429 responses, distributed rate limiting, and recommended retry strategies. I would also add tests to verify that the documented headers, tiers, and error contract remain aligned with the implementation, helping prevent documentation drift over time. My focus will be on clarity, accuracy, and keeping the documentation easy for API consumers to follow while ensuring the added assertions remain reliable and maintainable.

[Abioladory123]

@Abioladory123 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Interested in taking this on. I’ve worked across smart contracts, APIs, and frontend integrations, and I can start immediately.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Abioladory123 to this issue.

[drips-wave]

Congratulations, @Abioladory123! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Abioladory123: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊