Two limits keep the Alladdin API fast and fair for every customer: a per-minute burst guard and a monthly call quota.

⏱️ Burst + monthly 🔄 Retry-After header 📊 Tiered by plan rate-limiter healthy per second 3 / 50 per minute 1,103 / 1,500 per hour 3,180 / 5,000 Standard plan · resets in 14s

Overview

The Alladdin API enforces two limits in parallel on your account: a per-minute window that catches short spikes, and a monthly quota that caps total usage on your plan.

Limits scale with your plan. Higher tiers get bigger monthly quotas and faster burst rates for bulk operations.

How rate limits work

Two counters run in parallel on your account. Whichever one fills up first is the one that returns 429.

Per minute (burst)

Catches short bursts of activity. Keeps the platform responsive when an integration spikes or misbehaves.

Per month (quota)

Your total monthly call budget. Sized to comfortably cover the workload of the plan you're on.

Account-wide

Limits apply to your account as a whole. All API keys on the same account share the same counters, so adding more keys won't increase your budget. Upgrade your plan if you need more headroom.

Limits per plan

Each plan's monthly quota is sized for the invoicing volume it covers, with headroom for normal integration work (contact sync, product reads, reports).

Lower plans return HTTP 429 once the monthly cap is reached. Premium plans bill overage automatically when usage exceeds the cap (no hard stop, no surprise downtime).

Need more than Premium?

For sustained high-volume usage, dedicated rate limits, or custom enterprise integrations, we offer a metered plan with usage-based pricing on top of the Premium cap. Talk to sales to size a plan to your workload.

Talk to sales → →

When you hit a limit

The API responds with 429 Too Many Requests and a set of headers describing what was hit and when to retry. Use these instead of guessing.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 1500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715692800
X-RateLimit-Window: minute

{
  "type": "https://api.alladdin.com/problems/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have reached the per-minute limit (1500). Retry in 60 seconds."
}

Retry-After

Seconds to wait before retrying. Always honor this: it's the safest path.

X-RateLimit-Limit

The cap of the window that was hit.

X-RateLimit-Remaining

How many requests you have left in the current window.

X-RateLimit-Reset

Unix timestamp when the window resets.

X-RateLimit-Window

Which window triggered: minute or month.

Best practices

Build integrations that scale gracefully under load.

Honor Retry-After

Always wait the exact number of seconds returned. Don't retry sooner: the window hasn't reset.

Exponential backoff

For repeated 429s, increase the wait time on each retry: 1s, 2s, 4s, 8s. Add jitter to avoid thundering herds.

Batch when possible

Combine multiple operations in a single request where the endpoint allows it. Fewer calls, same result.

Use webhooks for events

Don't poll for changes. Subscribe to webhooks and receive updates in real time without consuming your budget.

Cache reads

Reference data (products, contacts, tax rates) changes rarely. Cache it locally and refresh on schedule.

Monitor your usage

Check X-RateLimit-Remaining on every response and slow down proactively when it drops.