Give failures a consistent meaning
A backend failure carries a named type, message reference and context instead of relying on a free-form exception string. Wildo uses that shared contract to shape the response and guide its handling.
Application code states what went wrong; clients and operators receive information suited to their different needs.
Example — Refuse an action that breaks a business rule
A service rejects an action using the business-rule error type. The client receives the corresponding message reference, while diagnostic context helps the operator understand which action was refused.
For engineers
Build a deliberate rejection
Inside a custom operation, use the supplied utils.errorBuilder and the current executionContext. This illustrative operation-body excerpt uses the shared error vocabulary; canProceed and recordId are values supplied by that operation:
if (!canProceed) {
throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
context: {
recordId,
operation: 'approve',
},
});
}
Import ErrorType and ErrorCustomMessageReference from @wildo-ai/saas-models. The reference chooses translated user wording; structured context explains the condition for diagnostics. A custom message needs a defined reference and translations, not a sentence smuggled into context.
Follow the contract to its consumers
| Authored information | Consumer and effect |
|---|---|
| Error type | Shared definition supplies status, severity and handling policy |
| Message reference | Frontend translation resolves the user-facing explanation |
| Execution context | Builder records operation and identity context |
| Correlation ID | Request-local fallback connects an error to its surrounding activity |
| Allowed structured details | Client serialization retains only the relevant context subset |
A missing explicit execution context does not mean inventing a new request identity: the builder uses the ambient request frame when present. A Wildo backend error is a structured object, not necessarily a native Error instance.
Preserve an already-classified failure
Use isWildoBackendError(error) when branching on a caught value. The builder’s conversion path preserves a classified error’s type and context rather than replacing it with an “unknown” error. Native exceptions are converted at the boundary, but their classification may depend on name/message heuristics; that is why authored request rejections should be explicit.
Error declarations describe several handling policies. A declared action is not evidence that an alerting or recovery integration is operating. Logging is deliberately owned by the handling boundary, not error construction. For a form field, prefer schema validation so the field-level error map can identify the affected input; use a business-rule rejection for a condition spanning the action.