calendar-plugin/requirements/error_model.md

Error Model Requirements

Purpose

Define a consistent error taxonomy and response structure across admin UI, API, CalDAV, and ICS surfaces.

Scope

This document covers:

• Error categories and stable codes
• API/CalDAV/ICS status behavior
• UI-facing error messaging principles
• Logging expectations for failures

Error Categories

• validation_error
• authentication_error
• authorization_error
• not_found
• conflict_error
• precondition_failed
• rate_limited
• integration_error
• internal_error

API Error Contract

JSON errors must include:

• error.code (stable machine identifier)
• error.message (safe human message)
• error.details (optional object/list with field-level data)
• error.request_id (optional correlation id)

Status mapping:

• 400 malformed payload/query
• 401 unauthenticated
• 403 unauthorized
• 404 not found
• 409 conflict
• 412 precondition failed
• 422 validation error
• 429 rate-limited
• 500 internal error

CalDAV/WebDAV Error Behavior

• Use standards-appropriate HTTP status codes and DAV error bodies.
• On multistatus operations, each href must report accurate per-resource status.
• Precondition failures must be explicit for conditional writes.

ICS Error Behavior

• Non-success ICS responses should return clear status (4xx/5xx) and not malformed calendar text.
• Internal diagnostics go to logs, not to public response bodies.

Admin UI Error Messaging

• Messages must be actionable and non-technical for end users where possible.
• Field-level validation errors must indicate affected field and remedy.
• Authentication/authorization failures should avoid revealing sensitive internals.

Retry Guidance

• Transient errors (rate limit, temporary integration failure) should indicate retry expectation.
• Permanent validation errors should not be presented as retriable without change.

Logging Requirements

• All 5xx and security-relevant 4xx failures must be logged.
• Logs should include actor, endpoint/action, status, timestamp, and request id.
• Logs must not include plaintext secrets/tokens/passwords.

Verification Requirements

Acceptance should verify:

• Error payload shape is consistent for API endpoints.
• CalDAV and ICS failures return standards-appropriate statuses.
• UI displays user-safe messages while logs retain troubleshooting detail.