The most dangerous assumption in scheduling infrastructure is: if we cannot confirm a provider is busy, they must be available.
A calendar timeout, OAuth expiration, or HTTP 429 from Google Calendar does not mean the provider is free. It means you do not know. These are different outcomes and they require different behavior.
Availability states
Orita uses six distinct availability states:
| State | Meaning |
|---|---|
| verified_available | Confirmed free via calendar |
| unavailable | Confirmed busy via calendar |
| unverifiable | Calendar connected but check failed |
| stale | Cached result older than threshold |
| calendar_disconnected | No calendar connected to this provider |
| not_checked | Availability not yet evaluated |
allowUnverifiable defaults to false. Providers with unverifiable or stale availability are excluded from resolution results unless the platform explicitly opts in.
What causes unverifiable
- Calendar returns HTTP 500
- Calendar returns HTTP 429 (rate limited)
- Network timeout during FreeBusy check
- OAuth token expired mid-request
- Calendar API returns malformed response
In every case, Orita does not treat the failure as free time. The provider is marked unverifiable and excluded.
Verification during hold
When a customer holds an option, Orita re-verifies availability in real time. It does not rely on the availability state from the resolution.
If the provider's calendar cannot be reached during the hold, the hold fails. This is intentional: a hold that cannot be verified is not a reliable reservation.
Verification during confirmation
Confirmation performs a fresh availability check as part of the re-validation step. If the calendar check fails at confirmation time, the confirmation fails with 409 BOOKING_CONFLICT.
The customer must try a different option or create a new resolution.
OAuth expiration
When a Google or Microsoft OAuth token expires, the connection transitions to reconnect_required. Orita emits a calendar.reconnect_required webhook event so the platform can notify the provider.
Providers with an expired connection cannot have their availability verified. They are excluded from resolution results by default.
What the platform must not do
A platform must not catch availability-check errors and substitute a default value of true. That assumption will eventually produce a double-booking.