# 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.