EVM - Handling "Response is too big" (-32008) on Debug Trace Methods

Tatum's EVM RPC nodes enforce a maximum response size per JSON-RPC call. When a response exceeds the configured limit, the node returns error code -32008:

{
    "id": 1,
    "jsonrpc": "2.0",
    "error": {
        "code": -32008,
        "message": "Response is too big",
        "data": "Exceeded max limit of 167772160"
    }
}

This is a node-side limit, not a gateway or network error. Retrying the same request will return the same error.

Current limits per chain

BSC Mainnet has been raised because certain blocks legitimately produce very large trace responses. On all other EVM chains, expect the 160 MiB default.

When you will hit this

The limit is almost always triggered by deep tracing methods on busy blocks, in particular:

• debug_traceBlockByHash
• debug_traceBlockByNumber
• debug_traceCall with the default (struct) tracer

The default tracer records opcode-level execution including stack and storage data at every step. A single BSC block can contain over 1.1 million EVM steps, which is enough to push one response past 500 MB.

Example request that exceeds the default 160 MiB limit on BSC:

curl --location 'https://bsc-mainnet.gateway.tatum.io' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByHash",
  "params": [
    "0x66ee087ec7e41ad1367187484f128ac96c745c7c746c63dd6378434353ab751a",
    { "timeout": "120s" }
  ],
  "id": 1
}'

Recommended workarounds

If you hit -32008, switch strategies rather than retrying.

1. Use callTracer instead of the default tracer

callTracer returns only the call hierarchy, not opcode-level state. Response sizes typically drop by one to two orders of magnitude.

curl --location 'https://bsc-mainnet.gateway.tatum.io' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByHash",
  "params": [
    "0x66ee087ec7e41ad1367187484f128ac96c745c7c746c63dd6378434353ab751a",
    { "tracer": "callTracer", "timeout": "120s" }
  ],
  "id": 1
}'

2. Add onlyTopCall: true if you only need the outer call

Skips internal calls entirely and returns the smallest useful trace.

{
  "tracer": "callTracer",
  "tracerConfig": { "onlyTopCall": true },
  "timeout": "120s"
}

3. Trace transactions individually with debug_traceTransaction

If you need full opcode-level detail, iterate through the block's transactions and trace each hash separately instead of tracing the whole block at once. Each per-transaction response stays well under the limit.

4. Enable compression on the wire

All Tatum gateways support gzip. Adding Accept-Encoding: gzip, deflate reduces bytes transferred, though it does not change the node-side size check that produces -32008. Use it in combination with the tracer changes above.

curl --location 'https://bsc-mainnet.gateway.tatum.io' \
--header 'Accept-Encoding: gzip, deflate' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--compressed \
--data '{ ... }'

Why the limit exists

The cap protects node stability and shared throughput. Serving multi-hundred-megabyte JSON payloads ties up connections, memory, and bandwidth that would otherwise serve many smaller requests. Raising the cap globally would degrade latency for the majority of workloads that never approach it.

BSC Mainnet is the current exception. We are not planning equivalent increases on other chains at this time.

Next Steps

1. Switch tracer: Retry the request with callTracer, adding onlyTopCall: true if applicable.
2. Fall back to per-transaction tracing: Use debug_traceTransaction per hash when opcode-level detail is required.
3. Contact support: If your use case genuinely requires responses beyond these limits on a specific chain, reach out with the method, chain, and a sample block or transaction hash so we can evaluate.