Cal.com Error Handlers

The Cal plugin includes built-in error handlers for common Cal.com API error scenarios.

Built-in Error Handlers

Rate Limit Errors

Triggers: HTTP 429 status

Behavior:

• Maximum retries: 5
• Respects Retry-After header

Example:

// Corsair handles rate limits automatically
const bookings = await corsair.cal.api.bookings.list({ 
    limit: 50,
});

Authentication Errors

Triggers: HTTP 401 status, invalid API key

Behavior:

• Maximum retries: 0 (no retries)
• Fails immediately

How to Fix:

1. Verify your Cal.com API key is valid
2. Check the key has not expired or been revoked in your Cal.com account settings

Not Found Errors

Triggers: HTTP 404 status, booking UID does not exist

Behavior:

• Maximum retries: 0 (no retries)

How to Fix:

1. Verify the booking UID exists
2. Check that the booking has not already been deleted

Conflict Errors

Triggers: HTTP 409 status, time slot already booked

Behavior:

• Maximum retries: 0 (no retries)

How to Fix:

1. Check availability before creating a booking
2. Select a different time slot

Network Errors

Triggers: Connection errors, timeouts

Behavior:

• Maximum retries: 3
• Uses exponential backoff

Custom Error Handlers

cal({
    errorHandlers: {
        SLOT_UNAVAILABLE: {
            match: (error) => {
                return error.message.includes("slot_unavailable"); 
            },
            handler: async (error, context) => {
                console.log("Requested time slot is no longer available");
                return {
                    maxRetries: 0,
                };
            },
        },
    },
})

For comprehensive error handling strategies, patterns, and best practices, see the Error Handling concepts page.