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.

Documented steps

1. 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.
2. 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.
3. 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.
4. 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.
5. Check the HTTP status on every request; a 429 means the rate limit for your auth tier was exceeded.
6. 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.
7. 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.
8. 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"}}.
9. 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.
10. Log error.code rather than only the HTTP status, since v2 error codes are more granular.
11. Docs: https://cal.com/docs/api-reference/v2/introduction