Each API key carries a per-minute rate-limit configuration (rate_limit_per_min),
set by the Saoma team when the key is issued.
Enforcement of these quotas is not yet active: the current API does not
reject traffic, and responses do not include X-RateLimit-* headers or
return 429. Treat the limit below as a soft guideline and a preview of the
enforced behaviour to come.
Guideline limits
| Category | Soft limit | Endpoints |
|---|
| Read endpoints | 60 req / min | GET /v1/venues, GET /v1/venues/{id}, …/treatments |
Planned behaviour (once enforced)
When enforcement ships, responses will include the following headers, and
requests over quota will return 429:
| Header | Description |
|---|
X-RateLimit-Limit | Your quota for the endpoint category |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets |
Retry-After | Seconds to wait before retrying (on 429) |
Best practices
- Cache venue and treatment data. Venue metadata and treatment catalogues
change rarely. Refresh them a few times per day, not on every user request.
- Implement exponential backoff for
429/5xx responses ahead of
enforcement, so your integration is ready when quotas go live.