A payment failure may contain API keys, internal codes, or customer data. Recovery needs an actionable public error; debugging needs the internal context. At a system boundary, wrap the failure in a safe error and preserve its cause. section 7.2.3
Catch placement matters too: catch too deep and recovery context may be missing; catch too high and details about the failure may be lost. Handle errors at semantic boundaries where recovery decisions make sense and useful debugging context can be preserved. section 7.5
Useful error-handling boundaries include:
- Transaction boundaries, where a handler can roll back a unit of work. section 7.5
- API boundaries, where code calls external services or libraries. section 7.5
- User-operation and resource boundaries, where a discrete action begins and ends or resources are acquired and released. section 7.5
Wrap a payment failure
A payment wrapper can throw a public-safe error while attaching selected details from the third-party error as its cause. Callers can inspect that context for debugging without making the original error the recovery-facing message. section 7.2.3
function updateUserProfile(userId, changes) {
const tx = db.beginTransaction();
try {
const user = tx.query('SELECT * FROM users WHERE id = ?', userId); #A
tx.query('UPDATE users SET ... WHERE id = ?', userId, changes); #A
tx.query('INSERT INTO audit_log ...', userId, changes); #A
tx.commit();
} catch (e) {
tx.rollback(); #B
throw new Error('Profile update failed', { cause: e }); #C
}
}The transaction handler groups several queries and a commit, rolls back on failure, then wraps the error with its cause. section 7.5








