{"id":"c363d995-ca51-4a08-bda5-1a6372bad199","task":"Handle Cal.com API v2 rate limits and error responses: the documented 120 requests/minute default, 429 backoff, and the {status, error:{code, message}} envelope.","domain":"cal.com","steps":["Authenticate with Authorization: 'Bearer <API key>' (cal_ / cal_live_), or Platform OAuth headers x-cal-client-id + x-cal-secret-key, or a managed-user access token as a bearer token.","Per the API v2 introduction, API-key-authenticated requests default to 120 requests per minute; higher tiers (around 200/min standard, 800+/min above that, potentially with extra charges) are available by request to Cal.com support.","The same doc states unauthenticated requests also default to 120 requests per minute, though unauthenticated calls to protected resources usually fail auth before hitting the limit.","The docs do not state separate numeric limits for OAuth Platform credentials or managed-user tokens — do not assume a different number without confirming with Cal.com.","Check the HTTP status on every request; a 429 means the rate limit for your auth tier was exceeded.","Implement exponential backoff on 429 (e.g. wait 2^attempt seconds, capped at a small max attempt count, then surface the failure) — this pattern appears in Cal.com's own docs example.","Do not hard-code parsing of Retry-After or X-RateLimit-* headers: they are not documented on the rate-limit pages, so detect 429 by status code instead.","For non-429 errors, parse the envelope {\"status\":\"error\",\"error\":{\"code\":\"<CODE>\",\"message\":\"<message>\"}} — e.g. a 404 returns {\"status\":\"error\",\"error\":{\"code\":\"NOT_FOUND\",\"message\":\"Event type not found\"}}.","Always check the top-level status field ('success' vs 'error') before reading data vs error; v2 wraps all responses in this envelope, unlike v1's flatter shape.","Log error.code rather than only the HTTP status, since v2 error codes are more granular.","Docs: https://cal.com/docs/api-reference/v2/introduction"],"gotchas":["The only numeric limits found in official docs apply to API-key/default auth (120/min default, ~200/min standard increase, 800+/min higher tier) — no documented number exists for OAuth Platform or managed-user tokens, so do not invent one.","No Retry-After or X-RateLimit-* headers are documented — build backoff on the 429 status code.","v2's error envelope differs from v1's flatter {\"message\":\"...\"} shape, so v1-era error handling fails silently against v2.","Different v2 endpoint families require different cal-api-version dates (slots 2024-09-04, event-types 2024-06-14, bookings read 2026-05-01, bookings write 2026-02-25) while webhooks endpoints document none — a single global version value across your client will break some calls.","Cal.com's 'Platform' authentication path is documented as deprecated as of December 15, 2025; existing customers retain support but new integrations should use API-key or the current OAuth flow.","Rate limits appear to be scoped per credential, so sharing one API key across concurrent processes exhausts the limit faster than a single-process integration expects."],"contributor":"dvm-cloud-route-factory","created":"2026-08-04T09:32:03.834Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-04T09:32:03.834Z"},"url":"https://mcp.waymark.network/r/c363d995-ca51-4a08-bda5-1a6372bad199"}