> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate-limit design

> Design 0xArchive clients around request rate, concurrency, credits, replay speed, plan gates, retries, and high-volume jobs.

Rate limits are implementation constraints, not just plan table rows. Use [Rate limits and credits](/rate-limits) for the public plan table and this page for the design concept behind those limits.

Rate limits are not only a number of requests per second. They are the combined envelope of request rate, concurrent queries, credit budget, route gates, WebSocket subscriptions, replay speed, retry behavior, and downstream processing capacity.

## Limit Types

| Limit type              | What it protects                       | Client design rule                                    |
| ----------------------- | -------------------------------------- | ----------------------------------------------------- |
| Requests per second     | API edge and account burst behavior    | Queue work and back off on `429`                      |
| Concurrent queries      | Heavy historical or long-running calls | Bound worker pools by route family                    |
| Credits                 | Volume and heavier data families       | Estimate before broad loops                           |
| WebSocket subscriptions | Live stream fanout                     | Subscribe only to required channel-symbol pairs       |
| Replay speed            | Historical stream pressure             | Bound windows, speed, and output storage              |
| Route gates             | L3, L4, replay, or advanced features   | Check plan and generated route docs before production |

## Client Pattern

<Steps>
  <Step title="Start narrow">
    Confirm one venue family, one symbol, one route, and one small window.
  </Step>

  <Step title="Separate heavy and light work">
    Do not let L3, L4, replay, or long-history jobs share an unbounded worker pool with freshness checks.
  </Step>

  <Step title="Back off with context">
    Preserve `meta.request_id`, route, symbol, retry count, and wait time when handling `429` or transient failures.
  </Step>

  <Step title="Store job shape">
    Save route family, symbols, windows, concurrency, and output destination so usage can be audited.
  </Step>
</Steps>

## Automation Guardrails

Scripts should not default to every symbol, every channel, or every historical window. A safe job names the route family and symbol scope, sets a limit, implements backoff, logs request IDs, and writes output incrementally. For broad exports, start with a bounded sample request before widening the run.

For WebSocket clients, rate limits interact with processing speed. A client that receives data faster than it can process will create stale dashboards, bad local books, or dropped replay messages even if the server accepts the subscription.

## Limit Checklist

Before increasing scope, store the limit checklist with the job.

| Field          | Capture                                                                        |
| -------------- | ------------------------------------------------------------------------------ |
| Scope          | Route family, symbol set, data family, and time window                         |
| Capacity       | Request rate, concurrent queries, credits, subscription count, or replay speed |
| Retry behavior | Backoff, jitter, max attempts, and status classes that stop the job            |
| Trace          | Request IDs, cursor state, output path, and data-quality decision              |
| Stop condition | Rate response, credit threshold, stale data, gap event, or consumer lag        |

## Next Step

Use [Limits and throughput](/guides/limits-and-throughput) for implementation details, [WebSocket limits](/websocket/limits) for stream-specific sizing, and [Credits](/core-concepts/credits) for capacity planning.