specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Cal.com
providerId: cal-com
created: '2026-05-08'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-08, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-08'
reconciled: false
tags:
- Productivity
- Scheduling
- Calendar
- Open Source
- Booking
- Rate Limiting
- Quotas
- Throttling
description: Cal.com API v2 returns 429 with a Retry-After header when rate-limit ceilings
  are exceeded. Limits are scoped per API key (or per OAuth client on Platform) and are
  not consistently published as exact per-second numbers. Self-hosted instances have no
  platform-imposed rate limit beyond the operator's infrastructure.
notes: For high-volume Platform integrations (managed users), coordinate with Cal.com to
  raise per-org rate ceilings. For booking-page traffic, prefer slot reservation flows
  over polling availability.
sources:
- https://cal.com/docs/api-reference
- https://github.com/calcom/cal.com
responseCodes:
  throttled: 429
limits:
- name: Cloud API Key
  scope: api_key
  metric: request
  limit: published per-key
  timeFrame: per-minute
  notes: Per-key request rate; honor Retry-After on 429.
- name: Platform OAuth Client
  scope: oauth_client
  metric: request
  limit: published per-client
  timeFrame: per-minute
  notes: Platform managed-user OAuth clients have their own ceilings; raised by contract.
- name: Self-Hosted
  scope: instance
  metric: none
  limit: -1
  notes: No platform-imposed limits when self-hosted; bounded by operator infrastructure.
policies:
- name: Backoff Strategy
  description: Exponential backoff with jitter on 429; honor Retry-After header.
- name: Use Webhooks Not Polling
  description: Subscribe to BOOKING_* events instead of polling the bookings endpoint.
- name: Reserve Slots Before Confirmation
  description: Use the Slots API to reserve a slot during the booking flow rather than
    re-querying availability multiple times.
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com