Rate limits

Know how many requests you can send, read how many you have left, and back off cleanly when you hit the limit.

Available at launch

Limits#

The sandbox has the same limits as production, so a load test there tells you what production will do. A parallel test suite can hit them too.

Member token limits are per token, so one guest's app can't use up your server's budget. Your server's calls on behalf of all guests share the secret key's 50 per second.

Headers#

Every response carries these headers:

1
2
3
4RateLimit-Limit: 50
RateLimit-Remaining: 47
RateLimit-Reset: 1
Request-Id: req_9Tn4Hx2pRb

When you hit the limit#

You get 429 rate_limited with a Retry-After header in seconds. The request did not run.

1
2
3
4
5
6
7
8
9{
  "type": "https://docs.unplugdining.com/reference/errors#rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "This key sent more than 50 requests in one second.",
  "param": null,
  "request_id": "req_2Vk7Qm9xWd"
}

1. Wait Retry-After seconds. Don't retry right away; that keeps you over the limit.
2. Retry with the same Idempotency-Key. A 429 is always safe to retry. The retry recipe handles it.
3. Add jitter when many workers retry. Otherwise they all come back in the same second and hit the limit again.

Staying under the limit#

• Cache what rarely changes. GET /v1/program, /v1/locations and /v1/rewards change only when someone edits the program. Cache them for a few minutes on your server.
• Preview once per cart change, not on every keystroke or screen render. Debounce quantity buttons.
• Use webhooks instead of polling. points.changed and order.credited tell you when a balance moves. See Webhooks.
• Spread batch jobs out. A backfill of 10,000 members at 50 per second takes under 4 minutes; run it with a fixed concurrency rather than all at once.

Asking for more#

If your traffic needs higher limits, for example for a launch or a large migration, email support@unplugdining.com. Include your brand name, the endpoints, the peak requests per second you expect, and when. Send a few Request-Id values from 429 responses if you're already hitting the limit.