Explicit Input Errors

Follow the Ensure Validation policy first. Use the shared validation API whenever possible and propose a reasonable extension before introducing manual validation. This policy defines the fallback only when that API and a reasonable extension cannot meet the requirement. Keep fallback validation in shared infrastructure and run it before making changes. Never raise or return the generic invalidRequest error. Reuse existing localized messages and ICU templates where their meaning matches the failure; otherwise use a specific reusable key describing the domain condition rather than a separate key for every field. Identify affected inputs through existing field-label keys and structured problems, without exposing raw sensitive values or provider responses. Raise the error through clientError; do not silently return success or check suppression flags inside business functions or validation helpers. A larger workflow may select specific input-error codes in its async context and invoke independent steps through runStep. clientError records eligible errors in the same context’s errors array and always throws; the shared step boundary controls continuation. Authorization, infrastructure and operation-consistency failures must propagate. Suppression does not roll back earlier writes, so validate first and keep dependent work within the same step.

Philosophy

Shared validation remains the first choice. Exceptional domain checks still need explicit diagnostics and consistent control flow. Keeping fallback errors in shared infrastructure lets the broader workflow decide whether independent work may continue, while the failing function always stops.

Correct

A reviewed fallback for domain validation that cannot reasonably use the shared API or an extension. The validation report comes from shared validation infrastructure.

if (validationReport.hasRelationCycle) {
    clientError('relationCycleDetected', {
        problems: validationReport.fields,
    })
}

Incorrect

if (validationReport.hasRelationCycle) clientError('invalidRequest')

if (validationReport.hasRelationCycle) {
    if (params.suppressErrors) return
    clientError('relationCycleDetected')
}

Fix

Apply the Ensure Validation policy first. For a reviewed fallback, centralize validation and use clientError with a precise reusable localized message and structured field details; keep suppression in shared context infrastructure.