# Errors, conflicts and retries

Recover from a failure without widening access or duplicating writes.

Source: https://docs.getridian.com/developers/errors/
Language: en
Reviewed: 2026-09-20

## Classify before retrying

| Situation | Recovery |
| --- | --- |
| Invalid input or unknown timezone | Correct the request; ask the user for missing intent |
| Expired/revoked authorization | Follow refresh or reconnect; do not broaden access |
| Excluded calendar or unsupported action | Change the workflow or obtain the appropriate explicit grant |
| Concurrent edit / ETag conflict | Read the current event, compare, then decide |
| Provider throttling or temporary failure | Back off; respect retry guidance when supplied |
| Timeout after a possible write | Treat the result as unknown; inspect or retry with the same operation key |

## Preserve operation identity

A creation retry is the same intended operation. Keep its original `requestId` and payload. A new key expresses a new creation and may create a duplicate. Changed input with an old key can be rejected as a conflict. Do not promise exactly-once behavior beyond the documented provider path.

Updates and deletes have provider-specific concurrency constraints. CalDAV uses strong ETags and conditional requests to avoid silently overwriting another editor. A missing object after deletion can be reported as already gone, not a newly executed delete.

## Incomplete availability is not free time

If a requested calendar cannot be checked, the client must not claim that all calendars are free. An empty provider result, a permission denial and a failed provider read have different meanings.

## Diagnose without copying content

Capture request ID when provided, operation, provider, time and sanitized error. Do not log tokens, app passwords, full provider responses or event descriptions. The current REST interface does not yet offer the full error/limit contract planned for partner integrations; handle the actual response instead of assuming a future schema.