Rate limits — boutique-scale by design

Rate limits on the Hotelminder API are deliberately conservative. Every module the platform ships was designed with the assumption that boutique properties do not need to hammer the API — a well-behaved integration on a 30-room hotel reads once every few minutes and writes rarely. The limits below reflect that shape.

Default limits per key and per property

Note that read-heavy operations (rates snapshots, availability polls, reservation lists) count toward the general per-property limit. Writes (module activations, basket edits, advisor scope events) count toward both the general and the writes bucket.

Response headers

Every response carries the X-Hotelminder-RateLimit-* family of headers so your integration can pace itself before it hits a 429.

X-Hotelminder-RateLimit-Limit: 500
X-Hotelminder-RateLimit-Remaining: 431
X-Hotelminder-RateLimit-Reset: 1753789200
X-Hotelminder-RateLimit-Bucket: property
X-Hotelminder-RateLimit-Concurrent: 3

The Reset value is a Unix timestamp for when the current window resets. The Bucket value tells you which bucket is closest to exhaustion — this is how your integration can react intelligently instead of blindly backing off.

Burst allowance for the pilot week

During the first seven days after a module activation, the per-property limit is temporarily raised to 1000 requests per rolling minute. This is deliberate — the initial rate reasoner tune, the initial fiscal composer shadow-invoicing week, and the initial Portfolio Sync Fabric baseline all read more than a settled steady state. The burst allowance drops back to 500 at the eight-day mark automatically. Advisors can extend the burst window by another seven days if a pilot week has been disrupted.

429 handling

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds). The correct client behaviour is to sleep for at least the number of seconds indicated and then retry the same request. Do not tighten your polling loop — the 429 means you are already reading too aggressively for a boutique-shaped platform.

HTTP/1.1 429 Too Many Requests
Retry-After: 24
X-Hotelminder-RateLimit-Bucket: property

{
  "error": "hm_429_rate_limit_exceeded",
  "message": "Per-property limit of 500 req/min reached; retry in 24 seconds.",
  "bucket": "property"
}