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

# Rate limits & Caching

> Paylead applies rate limits. Back off on 429, and cache safe reads.

Paylead enforces rate limits.

**Why this matters.** Hitting your Program's limit returns `429 Too Many Requests` and the call fails. A correct client treats `429` as expected back-pressure, backs off, and retries.

## Detecting throttling

A throttled call returns HTTP `429 Too Many Requests`.

Treat any `429` as the signal to back off, regardless of which headers are present.

## Back off correctly

Retrying a `429` immediately makes the problem worse. Use exponential backoff with jitter, and honor `Retry-After` whenever the platform sets it.

<Note>
  **Code examples coming soon.** The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
</Note>

<Tip>
  Always add jitter (a small random delay on top of the backoff). Without jitter, a fleet of clients retries in sync and re-hits the limit at the same moment.
</Tip>

## Cache safe reads

Most read endpoints are stable for seconds to minutes.

<Info>
  Some resources may be Consumer-specific, depending on how they're implemented and configured. We encourage caching them, but on a per-Consumer basis, to preserve these personalizations.
</Info>

| Endpoint                                                  | Suggested TTL |
| --------------------------------------------------------- | ------------- |
| [Brands](/glossary#brand) list                            | 1 hour        |
| [Offers](/glossary#offer) list                            | 5 minutes     |
| Offer details                                             | 5 minutes     |
| [Consumer](/glossary#consumer)[Rewards](/glossary#reward) | 30 seconds    |

<Note>
  Never cache Webhook payloads; the platform delivers them once. See [Webhooks](/program/user-journey/concepts/webhooks).
</Note>

## Avoid hitting the limit

* **Batch where the API allows it.** Prefer one call returning 100 items over 100 calls returning 1.
* **Subscribe to [Webhooks](/glossary#webhooks)** for state changes instead of polling.
* **Spread cron jobs.** Schedule back-office jobs at random minutes inside the hour, not on the round minute.
* **Talk to your account manager early.** If you expect a traffic spike (campaign launch, migration), request a temporary increase ahead of time.

## What's next

<CardGroup cols={2}>
  <Card title="Errors" icon="triangle-alert" href="/program/user-journey/errors">
    Other HTTP error codes and how to remediate.
  </Card>

  <Card title="FAQ" icon="circle-question-mark" href="/program/user-journey/faq">
    Common integration questions, answered.
  </Card>
</CardGroup>