Platform
Apex heap size too large: reduce what you retain
Find large Apex allocations, avoid duplicate payload representations and measure the heap limit in the transaction that fails.
A response body that fits in an HTTP request can still exhaust Apex heap during processing. The parsed object graph and intermediate strings may occupy memory alongside the original payload.
Start by measuring around allocation points: the query, response-body read, deserialization and transformation. Check the actual execution context with Limits.getLimitHeapSize() instead of copying a number from an old article. The current governor reference lists 10 MB synchronous and 25 MB asynchronous heap, with exceptions for particular contexts.
Measure allocations rather than payload length
This diagnostic fragment reports the transaction’s heap usage and ceiling. Place separate measurements around suspect operations; the returned usage is a point-in-time observation, not a prediction of the next allocation.
System.debug(LoggingLevel.WARN,
'Heap bytes: ' + Limits.getHeapSize() +
'/' + Limits.getLimitHeapSize());
The Limits reference documents these counters. Avoid logging the payload itself while diagnosing it. Record byte counts, input identifiers and the processing stage so that support can reproduce the failure without copying sensitive records into logs.
Look for multiple representations of the same data. A retained response string, an untyped JSON map, a second typed object and a serialized output can overlap. Remove representations that later steps don’t need, and reduce the size of each requested page at the external API.
Fetch and keep less data
Select only the fields the operation uses. If the task needs a total, evaluate an aggregate query instead of loading every row solely to add numbers in Apex. If you process records sequentially, avoid adding every processed object to another long-lived list.
A SOQL for loop helps process query results incrementally, but it doesn’t protect code that accumulates those results into a collection. Nor does it make every response from an external API stream automatically. Follow the allocation through the whole method.
Setting a variable to null may remove a reference; it is not a guarantee that memory becomes available at a precise point. Design smaller units of work rather than relying on forced cleanup that Apex doesn’t expose as an application control.
Choose a boundary that limits the peak
For large record sets, Batch Apex separates execute scopes into transactions. Keep each scope small enough for its related records and response data, and avoid retaining a growing payload in state across batches.
Test the largest expected record and the largest expected page separately. A small number of records can still contain large text fields or attachments. Confirm that retrying a failed chunk won’t duplicate external work.
Heap exceptions are uncatchable governor failures. The acceptance test should show bounded memory as input volume grows, alongside correct output. A successful test with unusually small records doesn’t establish that bound.