Exception Handling

Use this skill when Apex error handling is becoming part of the design, not just a syntax exercise. The goal is to prevent swallowed failures, preserve operational visibility, and return the right kind of error for the calling context without corrupting bulk processing.

Before Starting

• What is the entry point: trigger, controller, REST resource, Queueable, Batch, invocable, or scheduled job?
• Should one bad record fail the whole transaction, or is partial success acceptable?
• Where do production failures go today: custom log object, platform event, observability tool, or nowhere?

Core Concepts

Catch Expected Failures, Not Everything

Apex supports standard exception types such as DmlException, QueryException, and CalloutException, plus custom exceptions. Catch the most specific exception you can actually handle. Salesforce guidance is to catch expected exceptions, add context, and let unexpected exceptions propagate instead of masking the root cause. A blanket catch (Exception e) that returns null or false usually turns a debuggable failure into silent data loss.

Bulk DML Failure Semantics Matter

insert records; and update records; throw a DmlException on failure and stop the transaction. Database.insert(records, false) and Database.update(records, false) behave differently: they allow partial success and return Database.SaveResult[]. In bulk code, this choice is architectural. If the business process can tolerate some failures, inspect SaveResult per record and log or surface the rejected records. Do not wrap a whole bulk update in one try/catch and assume that makes it bulk-safe.

Boundary-Specific Error Translation

Different Apex boundaries need different failure behavior. In a trigger, business-rule failures generally belong on the record through addError, while unexpected exceptions should surface and roll back the transaction. In an Aura/LWC controller, raw system messages are poor UX, so map known failures to AuraHandledException with a human-safe message. In background jobs, user messaging is irrelevant; logging and retry classification matter more.

Log Once, At The Right Layer

Centralize logging at a service boundary or integration boundary. If every layer catches and logs the same exception, production monitoring fills with duplicates and the real signal disappears. Prefer a single structured log entry containing the operation, record IDs or correlation ID, failure type, and whether the exception was rethrown or transformed.

Common Patterns

Specific Catch With Domain Mapping

When to use: A service class knows how to turn a low-level Salesforce failure into a business-facing failure.

How it works: Catch DmlException or CalloutException, log structured context once, then throw a domain-specific exception or boundary-safe exception such as AuraHandledException.

Why not the alternative: Catching generic Exception in every layer hides the original failure and produces inconsistent messages.

Partial Success For Bulk Operations

When to use: A batch-like service should process as many records as possible even if some fail validation.

How it works: Use Database.insert/update/delete(records, false), inspect every SaveResult, and store or return the failed record IDs and messages.

Why not the alternative: A single update records; statement plus one catch block loses per-record visibility and fails the entire transaction.

Trigger Business Validation With addError

When to use: The user should be told exactly which record violates a business rule during DML.

How it works: Add errors to offending records in trigger context for expected business validation failures. Reserve thrown exceptions for truly unexpected or system-level faults.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

• Catch blocks are specific; generic catch (Exception e) is justified or removed.
• No catch block silently returns success, null, or false without logging or rethrowing.
• Bulk DML paths use SaveResult[] when partial success is required.
• Trigger code uses addError for expected business validation, not generic swallowed exceptions.
• User-facing controllers return safe, human-readable messages instead of raw internal stack traces.
• Logging happens once with operation context, record scope, and failure type.

Salesforce-Specific Gotchas

1. Unhandled trigger exceptions roll back the transaction — if a trigger throws unexpectedly, the entire DML operation fails, including unrelated records in the same transaction.
2. Database.update(list, false) does not throw for every row failure — record-level failures move into SaveResult[]; if you never inspect those results, you silently lose failures.
3. AuraHandledException is a boundary tool, not a service-layer base class — using it deep in service code couples business logic to UI transport concerns.
4. A debug-only catch block is effectively a swallowed exception — System.debug is not monitoring, and production users never see it.

Output Artifacts

Related Skills

• apex/async-apex — use when the real fix is moving work to Queueable, Batch, or Scheduled Apex instead of trapping errors in a synchronous transaction.
• apex/test-class-standards — use alongside this skill to verify negative-path assertions, exception expectations, and mock-based error scenarios.
• apex/trigger-framework — use when trigger structure is making exception handling chaotic or duplicated across multiple handlers.