# Rate Limits

> How the platform shapes traffic on the public API and how integrations should react to rate-limit signals.

Source: https://business-api-docs.youhodler.com/docs/concepts/rate-limits

The public API protects shared infrastructure with traffic-shaping
policies. Integrations should treat rate limits as part of the runtime
contract — not as exceptional failures — and react with backoff and
retry.

> **Coming soon:** Concrete per-endpoint and per-tenant limits are being prepared. This page will document the exact thresholds, the response headers used to expose remaining budget, and the recommended retry strategy.

## What To Expect

When this concept lands, the layer will cover:

- **`HTTP 429 Too Many Requests`** — the canonical response when a
caller exceeds an applicable limit. The body uses the standard
[error envelope](/docs/concepts/errors) with a stable `code`.
- **`Retry-After` header** — present on `429` responses, indicating the
minimum seconds before the next attempt has a chance of succeeding.
- **`X-RateLimit-*` headers** — exposed on every response (success or
failure) with the active limit, the remaining budget in the current
window, and when the window resets.
- **Per-actor scoping** — limits apply per service principal /
per human actor, so one noisy integration does not consume a
tenant's whole budget.

## Until Then

Until concrete numbers are published, integrations should already plan
for:

- **Exponential backoff with jitter** on `429`, `502`, `503`. Start at
~250 ms, cap at a few seconds, add randomness.
- **Idempotency keys on retries** so a retried `POST` does not
duplicate the operation. See
[Idempotency And Concurrency](/docs/concepts/idempotency-and-concurrency).
- **Bounded concurrency** in your client — most rate limits punish
parallelism more than throughput.