geointel/geointel/docs/ERROR_HANDLING_AND_STATUSES.md

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.