Conventions

Rate limits

The Properly Platform API applies two independent windows per API key. Both are surfaced in response headers and enforced with 429 plus Retry-After.

Windows

Window	Limit
Rolling 2 seconds	100 requests (about 50 req/s sustained with burst headroom of 100)
Rolling 24 hours	30,000 requests

A request blocked by the 2-second window does not consume daily quota.
These match the limits the legacy API already had, so a migrating integration keeps identical headroom. Sustained legitimate needs beyond this can be raised per key; contact support.

Headers

Authenticated responses carry:

X-RateLimit-Limit: the window maximum.
X-RateLimit-Remaining: requests left in the window.
X-RateLimit-Reset: unix seconds when the window resets.
Retry-After: on 429 only, seconds to wait.

The X-RateLimit-* headers may be absent in rare degraded conditions. Treat them as advisory and rely on 429 plus Retry-After for enforcement.

Response headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1789554133
x-request-id: 8c2f5b0e-…

Handling 429

The problem detail is Rate limit exceeded (rate) for the 2-second window or Rate limit exceeded (quota) for the daily one. Back off until Retry-After elapses, then resume.

429 Rate limit exceeded Carries Retry-After in seconds.

429 response

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 2
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789554133

{
  "type": "https://www.getproperly.com/developers/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Rate limit exceeded (rate)",
  "instance": "/v1/bookings",
  "code": "rate_limited",
  "requestId": "aQ3fT8xW1m"
}