74 lines
2.3 KiB
Markdown
74 lines
2.3 KiB
Markdown
# 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.
|