Per-plan limits
Rate limits scale with the plan. The number is the sustained per-minute ceiling, per portfolio, across all endpoints. Read and write share the same budget; internal cost accounting favours reads.
| Plan | Requests per minute per portfolio | Burst window | SLA credit |
|---|---|---|---|
| Chain Starter | 500 | 30 s at 2x | Best-effort |
| Group | 2 000 | 30 s at 2x | Best-effort |
| Enterprise | 5 000 per portfolio | 30 s at 3x | Yes — 5% of monthly fee per confirmed false-positive 429 |
Burst allowance
A 30-second burst window on top of the sustained ceiling absorbs realistic traffic spikes — an EOD sync, a bulk rate decision publish, or a nightly parity sweep. Enterprise portfolios get a 3x multiplier for the burst window; Group and Chain Starter get 2x. The token bucket refills continuously at the sustained per-second rate.
HTTP 429 handling
When the limit is exceeded the API returns HTTP 429 with the error body { "error": "rate_limited", "code": "SP-RATELIMIT-EXCEEDED", "retry_after_seconds": <n> }. The Retry-After HTTP header is set to the same integer number of seconds. Do not retry sooner than that.
Headers on every response
X-SuiteProfit-Ratelimit-Remaining: requests remaining in the current window at request time.X-SuiteProfit-Ratelimit-Reset: unix timestamp when the window fully refills.X-SuiteProfit-Ratelimit-Portfolio: the portfolio ID the budget was drawn from (useful when your OAuth client spans several portfolios).
Custom uplifts through your account manager
Enterprise portfolios can request custom lifts through their named account manager — for example, a temporary bump during a distribution-team migration, or a permanent lift for a portfolio with an unusual property count. Uplifts are approved within the same business day and take effect on the next window boundary. Chain Starter and Group plans do not receive custom uplifts; the path there is a plan change.
SLA credit on false positives
Enterprise plans include SLA credit for confirmed false-positive rate-limit responses — cases where our accounting undercounted refills or the limit engine returned 429 despite headroom. The credit is 5% of the monthly Enterprise fee per confirmed incident, capped at 30% per calendar month. File through sla@suiteprofit.org with the X-SuiteProfit-Ratelimit-* headers and the response ID; the audit stream carries the same identifiers, so verification is trivial.
Shared vs dedicated budgets
Budgets are per portfolio, not per OAuth client. Multiple integrations sharing a portfolio share one budget. Enterprise portfolios that host two operationally independent teams (for example, a revenue team and a finance team) can request dedicated budgets carved out of the portfolio ceiling through the account manager.
Best practices
- Batch reads. List endpoints accept up to 500 items per page on Enterprise, 200 on Group.
- Back off with jitter on 429 to avoid thundering-herd retries across a multi-property write.
- Prefer webhooks over polling. If you're polling
/rate-decisionsevery minute, subscribe torate.decision.publishedinstead. - Use idempotency keys on writes so retries after a network error do not double-write into Profitroom Suite.