# Error handling for events, Apex jobs and APIs

*Integration Architect Study Guide · Build Solution · Last updated October 16, 2026 · https://www.certifyforce.com/study-guide/integration-architect/build-solution/error-handling-for-events-apex-jobs-and-apis*

Match each integration option to its documented error-handling mechanism: publish results and callbacks for platform events, checkpoints and retryable exceptions for event triggers, Pub/Sub API stream retries and flow control, finalizers and BatchApexErrorEvent for Apex jobs, partial success for REST collections, and retry rules by failure type.

- Certification: Salesforce Integration Architect
- Exam section: Build Solution
- Study guide: https://www.certifyforce.com/study-guide/integration-architect

**Official exam objective:**

> Given a use case, determine error handling for different integration options.

## What the exam expects

- Handle platform event publishing failures from Apex: inspect each `Database.SaveResult`, retry temporary errors, and use a publish callback for the final result.
- Choose between `setResumeCheckpoint()` and `EventBus.RetryableException` in an event trigger, and explain what happens when a trigger reaches the error state.
- Recover Pub/Sub API publish and subscribe streams after errors, size fetch requests with flow control, and route each error code to automatic retry or to an engineer.
- Attach recovery to Apex jobs: Transaction Finalizers for Queueable jobs, `BatchApexErrorEvent` for Batch Apex.
- Design API error handling: `allOrNone=false` partial success, retry strategy by failure type, and logging and rollback standards.

Key terms: **publish callback** (Apex class that receives the final, asynchronous publish result); **resume checkpoint** (replay ID after which a failed trigger restarts); **error state** (a trigger that exhausted its retries and stopped receiving events); **flow control** (a Pub/Sub client requests only as many events as it can process); **Transaction Finalizer** (a `System.Finalizer` that runs after a Queueable job ends); **partial success** (valid records commit while failed ones return errors).

## Key facts

| Fact | Detail | Source |
|---|---|---|
| `EventBus.publish()` exceptions | None for failed publishes; inspect each SaveResult | [Publish Event Messages with Apex](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_publish_apex.htm) |
| Successful SaveResult | `OPERATION_ENQUEUED`: queued, not finally published | [Publish Event Messages with Apex](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_publish_apex.htm) |
| Publish callbacks | High-volume events only; run as Automated Process | [Apex Publish Callbacks](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_publish_callbacks.htm) |
| Trigger retry cap | Initial run plus 9 retries, then error state | [Retry Event Triggers](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_subscribe_apex_refire.htm) |
| Events during error state | Not resent; fix and save the trigger | [Retry Event Triggers](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_subscribe_apex_refire.htm) |
| Publish stream idle timeout | 1,800 seconds, then CANCELLED | [Handle Errors](https://developer.salesforce.com/docs/platform/pub-sub-api/guide/handling-errors.html) |
| Max events requested per Subscribe call | 100 across all fetch requests | [Pull Subscription and Flow Control](https://developer.salesforce.com/docs/platform/pub-sub-api/guide/flow-control.html) |
| Finalizer re-enqueues | 5 consecutive failures; counter resets on success | [Transaction Finalizers](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_transaction_finalizers.htm) |
| BatchApexErrorEvent | Needs `Database.RaisesPlatformEvents`; fires for limit exceptions | [Firing Platform Events from Batch Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_batch_platformevents.htm) |
| sObject Collections `allOrNone` default | false; up to 200 records per request | [Update Records Using sObject Collections](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_sobjects_collections_update.htm) |

## Check yourself

- Why can't a try-catch block around `EventBus.publish()` detect failed publishes?
- When should a platform event trigger throw `EventBus.RetryableException` instead of setting a checkpoint?
- What must a Pub/Sub API client do after any error ends its Subscribe stream?
- Why does a batch job implement `Database.RaisesPlatformEvents` instead of catching exceptions?
- When should a REST integration set `allOrNone` to false?

## Sources

- [Handle Errors (Pub/Sub API)](https://developer.salesforce.com/docs/platform/pub-sub-api/guide/handling-errors.html)
- [Retry Long-Lived RPC Calls After an Error Occurs](https://developer.salesforce.com/docs/platform/pub-sub-api/guide/retry-rpc-calls.html)
- [Pull Subscription and Flow Control](https://developer.salesforce.com/docs/platform/pub-sub-api/guide/flow-control.html)
- [Pub/Sub API General Considerations](https://developer.salesforce.com/docs/platform/pub-sub-api/guide/considerations.html)
- [Publish Event Messages with Apex](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_publish_apex.htm)
- [Platform Event Error Status Codes](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_error_status_codes.htm)
- [Apex Publish Callbacks](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_publish_callbacks.htm)
- [Comparing setResumeCheckpoint() and EventBus.RetryableException](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_subscribe_compare_checkpoint_retryable.htm)
- [Retry Event Triggers with EventBus.RetryableException](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_subscribe_apex_refire.htm)
- [Subscribe to Platform Event Notifications with Apex Triggers](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_subscribe_apex.htm)
- [Best Practices for Writing Platform Event Triggers](https://trailhead.salesforce.com/content/learn/modules/platform-events-debugging/apply-best-practices-writing-platform-triggers)
- [Transaction Finalizers](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_transaction_finalizers.htm)
- [Firing Platform Events from Batch Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_batch_platformevents.htm)
- [Update Records Using sObject Collections](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_sobjects_collections_update.htm)
- [Well-Architected: Reliability](https://architect.salesforce.com/docs/architect/well-architected/guide/reliability.html)
- [BatchApexErrorEvent](https://developer.salesforce.com/docs/platform/platform-events/guide/sforce-api-objects-batchapexerrorevent.html)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 12 linked practice questions, and unlimited timed mock exams are included with the Integration Architect pack (USD $19): https://www.certifyforce.com/practice-exams