Pista errors are defined in pista-common/src/main/resources/error/error-classes.json and constructed through PistaErrors or specialized error helpers.
An error definition contains a stable error class and a parameterized message. Public error classes should identify the failed capability without exposing credentials, complete SQL text, connection strings, or business data.
- Configuration and capability failures should occur before external side effects.
- Spark exceptions should preserve the Spark error class and root cause where possible.
- Connector errors should identify the target operation and recovery action without logging secrets.
- A continue policy must record the failure in the execution report.
- Unknown remote commit outcomes must not be rewritten as success.
- Add or reuse a stable entry in the error catalog.
- Add a typed construction method.
- Preserve the original cause.
- Add tests for the error class, parameters, message loading, and redaction.
- Update public documentation when the error is user-facing.
Renaming, merging, or deleting an error class requires an explicit compatibility decision. Do not reuse an existing error class for an unrelated condition.
The generated catalog is authoritative for the complete current inventory.