Why a Google Calendar FreeBusy Error Is Not an Open Provider Slot

A Google Calendar FreeBusy error is not an open provider slot. The freeBusy.query response can report errors for an individual calendar or an expanded group. When that happens, the integration does not have reliable occupancy data for the affected provider. It should treat the result as indeterminate, not convert the absence of usable busy intervals into availability.

The API also places exact limits on expansion: at most 100 calendar identifiers from one group and at most 50 calendars in one query. Those limits matter in a multi-provider clinic. A request can be structurally valid while one calendar cannot be computed, cannot be found, or exceeds an expansion boundary.

What does a FreeBusy response actually establish?

Google documents POST https://www.googleapis.com/calendar/v3/freeBusy as a query for free and busy information across a set of calendars. The request supplies timeMin, timeMax, an optional response timeZone, expansion limits, and calendar or group identifiers. The returned structure separates group results from calendar results.

For a calendar that was computed successfully, the busy array contains time ranges. Google defines each busy start as inclusive and each end as exclusive. An empty busy array can support a free result only when the calendar result itself is valid for the requested interval. The response shape also permits an errors array on that same calendar.

Operational inference: make result validity a separate field from the busy interval list. A calendar with no busy intervals and no error is different from a calendar whose computation failed. Collapsing both cases into an empty array creates a false opening. Jane has its own calendar coverage boundary, described in why secondary Google calendars do not block Jane online booking.

Which errors must the availability parser inspect?

The official response schema includes groups.(key).errors[] and calendars.(key).errors[]. Google lists groupTooBig, tooManyCalendarsRequested, notFound, and internalError as possible reasons. It also warns that new error types may be added, so a client cannot safely rely on a closed list.

Parse errors before turning intervals into appointment slots. A notFound result means the requested resource was not found and may point to a stale identifier. An internalError is not evidence that the calendar contains no events. Expansion errors show that the requested set was not computed within the stated boundary.

Operational inference: use a small outcome model such as valid, temporarily indeterminate, and configuration error. The Google source does not prescribe those labels. It does establish enough structure to prevent the unsafe shortcut of treating every non-busy result as free. Log the calendar reference, query window, reason, and attempt without copying event details.

How should the 100-member and 50-calendar limits be handled?

groupExpansionMax controls the number of calendar identifiers returned for one group and has a maximum value of 100. calendarExpansionMax controls the number of calendars for which FreeBusy information is provided and has a maximum value of 50. A group larger than the configured group limit returns an error.

Do not solve a limit error by dropping calendars silently. That would make omitted providers appear available if downstream code assumes the request covered everyone. Keep the expected provider set beside the returned set, and require every expected calendar to reach a valid result before publishing its slots.

Operational inference: divide a larger roster into deterministic groups of no more than 50 calendars, then merge only validated results for the same query window. If the clinic uses Google Groups, resolve and compare group membership deliberately rather than assuming one group call proves complete coverage. Chunking is an integration method derived from Google’s cap, not a workflow mandated by Google.

Why do time bounds and time zones need separate checks?

Google requires timeMin and timeMax as RFC3339 date-time values. The optional timeZone controls the zone used in the response and defaults to UTC. These fields describe the query and presentation window. They do not decide the clinic’s appointment duration, buffer rules, provider location, or booking horizon.

Compare the returned timeMin and timeMax with the requested range before generating openings. Normalize intervals to one approved scheduling zone, then apply clinic rules after occupancy is known. A UTC response is not wrong, but displaying or slicing it as local time without conversion can shift a busy interval into the wrong provider day.

Operational inference: test local midnight and local clock changes for every operating zone. The source defines the API fields, not the clinic’s time-zone policy. Keep that policy explicit and avoid browser-derived defaults in server-side availability calculations.

What permission is sufficient for occupancy checks?

Google’s calendar-sharing documentation defines freeBusyReader as permission to see whether a calendar is free or busy without access to event details. The role can use freeBusy.query. This is narrower than reader, writerWithoutPrivateAccess, writer, or owner.

Use the narrow role when occupancy is the only business need. A scheduling layer does not need meeting titles, descriptions, guest lists, or other event content to subtract busy periods. Domain settings can still restrict the effective access granted to a Google Workspace user, so a configured ACL is not proof that every query will succeed.

Sharing a calendar also does not automatically insert it into a user’s CalendarList. Do not use visibility in the Google interface as the sole test of API access. Verify the exact calendar identifier and the FreeBusy result. For broader booking data boundaries, see minimum necessary fields for a booking integration.

What is a safe slot-generation sequence?

A safe sequence proves coverage before it publishes availability. Start with the expected provider calendars and one explicit RFC3339 interval. Send queries within the documented expansion limits. Inspect group errors, calendar errors, returned identifiers, and interval bounds before reading any busy array.

1. Resolve the approved calendar identifier for every provider in scope.
2. Split requests so no query asks for more than 50 calendars.
3. Send identical time bounds and the approved response time zone.
4. Reject or quarantine every group or calendar carrying an error.
5. Subtract busy intervals only for calendars with valid results.
6. Apply clinic duration, buffer, and booking-window rules afterward.
7. Publish slots only for providers whose coverage is complete.

This ordering keeps calendar truth ahead of presentation logic. It mirrors the replacement-safety principle in Zocdoc provider-day timeslot updates: unknown upstream state should stop publication rather than erase or invent availability.

How should retries avoid accidental double booking?

The two cited Google pages describe the FreeBusy contract and sharing roles, not a complete retry policy for clinic scheduling. Operational inference: retry transient failures within a bounded window, but keep the affected provider unavailable until a valid response arrives. A cached result may be used only under a documented clinic policy with an explicit age ceiling.

Do not convert a retry timeout into an empty busy array. Return an unavailable or temporarily indeterminate state to the booking interface. Preserve enough evidence to diagnose the failed calendar without storing event content. If the system later publishes a slot, it should use a fresh validated query rather than the failed response.

Reconciliation should compare the provider set requested, the calendars returned, their error arrays, and the slots eventually published. After a booking exists, asynchronous updates need a different check. The guide to idempotent and auditable booking webhooks covers duplicate delivery and state reconciliation.

What acceptance test proves the boundary?

Use synthetic calendars and neutral events. First query a calendar with one known busy interval and confirm that the interval removes the expected opening. Then query an invalid calendar identifier and confirm that the provider becomes indeterminate rather than fully free. Repeat with enough test identifiers to exercise the local chunking path.

Record the request window, response zone, expected identifiers, returned identifiers, error reasons, and publication decision. Do not put patient names, treatment details, or appointment reasons into test events or logs. The test concerns occupancy and error handling, not clinical content.

Pass only when every expected provider has either a valid computed result or an explicit blocked state. A successful HTTP exchange alone is insufficient because the documented response body can carry errors for specific groups or calendars.

Frequently asked questions

Does an empty busy array always mean the provider is free?

No. It supports that conclusion only for a valid calendar result covering the requested interval. If the calendar or its group has an error, availability is indeterminate and should not become an open slot.

Can one FreeBusy request cover 70 provider calendars?

Google documents a maximum calendarExpansionMax of 50. An integration with 70 calendars should split the work into bounded requests and verify that every expected calendar produced a valid result before merging availability.

Do I need permission to read event titles?

No, not when the integration only needs occupancy. Google’s freeBusyReader role reveals whether time is free or busy without granting access to event details.

Should an internal error reopen the provider’s day?

No. internalError means the computation failed. Treating it as a free calendar would be an unsafe operational inference. Keep the provider blocked or indeterminate until a valid result is available.

References

• Google for Developers, “Freebusy: query,” reviewed August 16, 2026, https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query.
• Google for Developers, “Calendar sharing,” reviewed August 16, 2026, https://developers.google.com/workspace/calendar/api/concepts/sharing.