API Error Taxonomy for File Pipelines
Define stable, actionable error classes for upload and processing APIs.
code
security
document
image
video
audio
archive
Why Error Taxonomy Matters
Without a stable taxonomy, clients and support teams cannot distinguish user mistakes from platform defects. A typed error model improves retry logic, telemetry quality, and incident triage.
Recommended Classes
- input_invalid: malformed or policy-violating user input.
- type_mismatch: extension/signature/parser disagreement.
- processing_failed: decode/transcode/extraction failure.
- resource_limited: quota, timeout, or concurrency budget exceeded.
- internal_error: unexpected service fault.
Operational Rules
Each class should map to deterministic status codes, retry policy, and user-facing message patterns. Instrument metrics by class and reason code so regressions are measurable.