Skip to main content
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.
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.
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.

​
Cache safe reads

Most read endpoints are stable for seconds to minutes.
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.
EndpointSuggested TTL
Brands list1 hour
Offers list5 minutes
Offer details5 minutes
ConsumerRewards30 seconds
Never cache Webhook payloads; the platform delivers them once. See Webhooks.

​
Avoid hitting the limit

  • Batch where the API allows it. Prefer one call returning 100 items over 100 calls returning 1.
  • Subscribe to 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

Errors

Other HTTP error codes and how to remediate.

FAQ

Common integration questions, answered.