docs: rate limits table with search

[unatasha8]

• I have read the contributing guidelines and signed the CLA.
• I have referenced an issue containing the design document if my change introduces a new feature.
• I have read the security policy.
• I confirm that this pull request does not address a security vulnerability.
  If this pull request addresses a security vulnerability,
  I confirm that I got approval (please contact security@ory.com) from the maintainers to push the changes.
• I have added tests that prove my fix is effective or that my feature works.
• I have added the necessary documentation within the code base (if appropriate).

Further comments

[jhickmanit]

Should we split the technical below into another document? It feels odd to get into the "how" when we are explaining the why above.

[unatasha8]

I think if we split it, they won't see/read it... the above is 'what' project rate limits are and below is 'how' they need to implement them

[tricky42]

Hey Una,

Here's the banner text, along with a proposal for a small restructuring that I think makes the overall navigation cleaner.

Proposed structure

Three pages:

• /rate-limits — new parent/overview page (already drafted, can share the file)
• /rate-limits-legacy — the current /rate-limits content, unchanged
• /rate-limits-new — stays as-is

The key benefit: since /rate-limits becomes the overview page, every customer who has that URL bookmarked will automatically land there and see the migration notice — before navigating to whichever detail page applies to them. No extra promotion needed; the restructuring does the communication work for us.

New visitors coming via search will also land on the overview first, which means everyone gets context on old vs. new before diving into the details.

The banners on the detail pages are then a secondary safety net for anyone who arrives there directly.

Banner text for /rate-limits-legacy:

This page describes the legacy rate limiting system, which applies to existing Ory Network customers who haven't been migrated yet. If you're a new customer or have already been migrated, see the new rate limits. Learn about both systems and the migration plan → /docs/guides/rate-limits

Banner text for /rate-limits-new:

This page describes the new rate limiting system, which applies to all new Ory Network customers and existing customers after migration. If you're an existing customer and haven't received a migration notice yet, see the legacy rate limits. Learn about both systems and the migration plan → /docs/guides/rate-limits

Both banners: info severity.

One open item on the parent page: I included a note that customers can check which system applies to them in the Ory Console under Settings → Rate Limits. That's just an idea for now — would actually be quite simple to implement and a nice touch, but it's not there yet. I've marked it as a placeholder so we can either build it or drop the reference before publishing.

Let me know if the restructuring works for you!

rate-limits.md

[tricky42]

Hey @unatasha8 @wassimoo,

I reviewed all five pages in the preview and want to propose restructuring the pages under rate-limits-new. The top-level split (rate-limits → rate-limits-legacy / rate-limits-new) is good — let's keep that.

Problem with the current sub-pages
rate-limits-project and rate-limits-endpoint fragment a single mental model forcing customer to read both pages to understand how the new system works. The endpoint content (volumetric + inflight) is also nearly identical to what's already on rate-limits-legacy, which means we're maintaining the same text in two places.

Proposed structure

rate-limits                        (parent: shared concepts + routing)
├── rate-limits-legacy             (legacy project thresholds only)
├── rate-limits-new                (new system concepts: buckets, naming, shared counters)
│   └── rate-limits-new-reference  (pure lookup: interactive threshold table + all numbers)

What moves to the parent page
Since endpoint-based protection (volumetric + inflight), rate limit headers (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset), 429 handling, and the exponential backoff example are identical between legacy and new — they belong on the parent page. Every customer passes through it regardless of which system they're on, and it eliminates the duplication.

The parent page would cover: which system applies, migration plan, endpoint-based protection (volumetric + inflight tables), HTTP headers, and 429 handling. Everything shared lives there.

What stays on the child pages
Only what's specific for the legacy and new system:

• rate-limits-legacy — legacy project rate limit tables by plan/env.
• rate-limits-new — concepts page for the new system. Buckets (naming convention, shared counters), burst vs sustained, how project limits are structured differently from legacy.
• rate-limits-new-reference — pure lookup page. The interactive threshold table (tier × env × bucket).

This way, each page has a clear job: parent = shared behavior, legacy = old thresholds, new = new concepts, reference = new thresholds.

Other items I noticed across the pages:

• Volumetric row in the legacy endpoint table says "To be added later" — remove it
• The backoff code example has no jitter — minor but worth adding

I setup a call later on to discuss this proposal.

[tricky42]

Following up on the call with @unatasha8 we agreed on the general structure:

rate-limits                        (parent: routing to legacy vs new)
├── rate-limits-legacy             (legacy system, self-contained)
├── rate-limits-new                (new system concepts, self-contained)
    └── rate-limits-new-reference  (pure lookup: interactive threshold table)

One change to the proposal: shared concepts (endpoint-based protection, HTTP headers, 429 handling, backoff) should not move to the parent page. Instead, keep them on both rate-limits-legacy and rate-limits-new so each page is self-contained.

Why: When we retire the legacy system, we want a clean cutover — just remove rate-limits and rate-limits-legacy, then promote rate-limits-new to rate-limits. If shared content lives on the parent page, that move becomes a content migration. If each child page is self-contained, it's just a rename.

The parent page (rate-limits) becomes a lightweight routing page, which includes the system that applies to you, the migration timeline, and links to the appropriate child page.

Everything else from the original proposal (collapsing rate-limits-project + rate-limits-endpoint into a single rate-limits-new concepts page, and a separate reference page for thresholds) still stands.

[unatasha8]

@tricky42 Not following your comments... The top level 'rate-limits' only contains info about whether the legacy or new rate limits apply to the user. Below are the rate-limits-legacy and rate-limits-new files. Both contain the shared concepts: HTTP headers, 429 handling, backoff etc. with new also explaining new buckets. Legacy does contain project and endpoint content, where as New is broken down into to pages: project & endpoint.

This is a better devision of the contain for find ability, SEO, etc. When legacy is removed, we still just need to remove the top level and the legacy files. Then New becomes rate-limits.