Rate limits

Two limits apply: a sliding monthly quota and a per-minute spike limit. Both are enforced per key and reset on the boundary of the window.

Limits by tier

Response headers

Every successful response includes:

X-RateLimit-Tier: starter
X-RateLimit-Remaining-Minute: 287
X-RateLimit-Remaining-Month: 49823

When you go over

You'll receive HTTP 429 with one of two codes: rate_limited (per-minute) or monthly_quota_exceeded. A Retry-After header tells you how many seconds to wait.

{
  "error": {
    "code": "rate_limited",
    "message": "Per-minute rate limit exceeded. Slow down and retry shortly.",
    "docsUrl": "/developers/docs/rate-limits"
  }
}

Stretching your quota

Cache. Every read endpoint returns a Cache-Control: public, s-maxage=… header — saint and country details cache for ten minutes, calendar for ten minutes, the OpenAPI spec for an hour. A CDN in front of your code or a thirty-second in-memory cache typically eliminates 90% of duplicate requests.