# Error Handling and Statuses

## API error contract

All expected errors return `ApiError`.

Examples:

- `validation_error`
- `not_found`
- `unsupported_dataset_type`
- `invalid_geometry`
- `dependency_not_configured`
- `processing_failed`
- `file_too_large`

## Job/analysis statuses

Use these statuses consistently:

- `queued`
- `running`
- `completed`
- `failed`
- `cancelled`
- `not_configured`

## Dataset statuses

- `created`
- `metadata_pending`
- `metadata_ready`
- `metadata_failed`
- `processing`
- `ready`
- `failed`

## Frontend display rules

- Never show raw stack traces.
- Show the user what failed and what they can do next.
- For `dependency_not_configured`, show which feature flag or environment variable is missing.
- For geospatial errors, include CRS/geometry hints when available.

## Logging

Backend should log:

- request id if available
- project id when relevant
- dataset id when relevant
- analysis run id when relevant
- exception summary

Do not log secrets or large file contents.