Error taxonomy
Starfire errors should tell you which subsystem failed and what kind of response is appropriate. A useful error is more than a generic “something went wrong.”Error categories
Error information to capture
For a supportable error, collect:- request ID
- resource ID such as run/build/artifact/project
- timestamp
- active account or organization context
- action being attempted
- visible error code/category
- whether retry changed the result
Retry rules
Retry temporary conditions such as rate limits, provider failures, or transient service errors according to returned guidance. Do not repeatedly retry invalid input, denied permissions, expired credentials, hard credit ceilings, or permanently failed resources.User-facing vs operator-facing errors
The user-facing message should explain what the user can do. Control Center can expose deeper diagnostics such as provider route, worker stage, reconciliation state, or failure metadata to authorized operators.As the public Developer Platform stabilizes, endpoint-specific stable error codes can be added beneath this taxonomy without changing these higher-level categories.