Calendar API 412 Precondition Failed or 410 Gone? Don't blind-retry or re-auth — here's the fix

Calendar APIs (Google Calendar, Microsoft Graph) return two errors that agents reliably mishandle: 412 Precondition Failed and 410 Gone. Both are recoverable — but the naive responses (retry the same request, or re-authenticate) are exactly wrong, and one of them double-books.

412 Precondition Failed: someone edited it first

You fetched an event, got its ETag, made a change, and sent the update with If-Match: <etag>. The 412 means the ETag no longer matches — the event was concurrently edited since you fetched it. This is optimistic-concurrency protection: a lost-update guard, not a transient failure.

410 Gone: the sync token is dead (not an auth problem)

During an incremental sync, 410 Gone (often with fullSyncRequired) means your sync token / delta token expired or was invalidated. The server can no longer give you an incremental diff from that point.

The common misdiagnosis is to treat 410 as an auth/permissions error and re-authenticate — which does nothing, because your credentials are fine. The fix is a full re-sync: discard the dead token, do a full sync to get a fresh sync token, then resume incremental syncing from there.

For agents managing calendars

An agent that retries a 412 double-books, and one that re-auths on a 410 spins uselessly. diagnose_infra_error returns the calendar family with the correct handling for each — re-fetch-and-reapply for 412, full-resync for 410:

diagnose_infra_error({error: "410 gone fullSyncRequired sync token"})
// → { family: "calendar",
//      fix: "sync token expired — do a FULL re-sync for a fresh token; NOT an auth error" }