Timeout
A Timeout in Salesforce is the maximum time allowed for a transaction, callout, query, or session to complete before the platform terminates it.
Definition
A Timeout in Salesforce is the maximum time allowed for a transaction, callout, query, or session to complete before the platform terminates it. Salesforce enforces timeouts at multiple layers: synchronous Apex execution (10 seconds CPU time, longer for async), HTTP callouts (60 seconds per callout, configurable down to 1 second), SOQL queries (120 seconds for the platform to return results), user sessions (configurable from 15 minutes to 24 hours), API session lifetime (8 hours default), and Salesforce Connect external object queries (120 seconds). Hitting a timeout terminates the operation and returns a timeout exception to the caller; the partial work is typically rolled back to keep the platform consistent.
Timeouts exist to protect the multi-tenant platform from runaway processes that would consume shared resources at the expense of other customers. They are not platform bugs to work around but design constraints to design with: write Apex that completes within governor-limit windows, build integrations that respect callout limits, and architect workflows that fit within session lifetime expectations. Hitting timeouts in production usually means the workload exceeded what the chosen execution context supports.
Timeouts on the Salesforce platform: per-context limits and how to design around them
Apex CPU timeout: the 10-second synchronous limit
Synchronous Apex transactions have a 10-second CPU time limit (the platform tracks CPU time, not wall-clock time, so I/O waits do not count). Asynchronous Apex (@future, Queueable, Batch, Schedulable) has higher CPU limits, typically 60 seconds. The CPU clock starts when the transaction begins and accumulates across every line of executed code, including loops, method calls, and DML operations. Hitting the limit raises a System.LimitException with an Apex CPU time limit exceeded message and rolls back the transaction. Common culprits: deeply nested loops over large collections, recursive triggers, expensive sObject SOQL queries inside loops, complex JSON parsing on large payloads. The standard mitigations are: bulk-safe code (operate on collections, not single records), short trigger handlers, and asynchronous execution for any work that genuinely needs more than 10 seconds.
HTTP callout timeout: configurable per request
Apex HTTP callouts to external endpoints have a default timeout of 10 seconds and a maximum of 120 seconds. Set the timeout per HttpRequest with request.setTimeout(milliseconds). Lower timeouts protect the caller from slow external endpoints; higher timeouts accommodate genuinely slow services. For asynchronous Apex (Queueable, Batch), the maximum extends to 120 seconds; for synchronous Apex, the maximum is also constrained by the overall 10-second CPU limit unless the callout uses Continuation, which lets the platform release the synchronous transaction while waiting for the response. Continuation is the pattern for long-running callouts in synchronous Apex; without it, the callout blocks until response or timeout, which often exceeds the CPU limit when the external service is slow.
Session timeout: user session lifetime
User sessions in Salesforce have a configurable timeout that determines how long a session id remains valid after the last user activity. The default is 2 hours; the range is 15 minutes (high security) to 24 hours (low security, browser-based long-running sessions). Configure the session timeout per profile through the profile Session Settings, or set the org-wide default through Setup, Session Settings. After the timeout, the user session id is invalidated and any subsequent action requires re-authentication. For integration users that need long-running sessions (a daily batch job, an overnight data warehouse pull), pick a longer timeout or use OAuth refresh tokens to get a fresh session id at the start of each operation. Avoid Forever session timeouts; they expand the attack window if credentials leak.
SOQL query timeout and the data volume problem
SOQL queries have a 120-second timeout for the platform to return results to the caller. Most queries return in well under a second, but queries against very large objects (millions of records), queries with leading wildcards on unindexed fields, and queries with complex sharing-rule evaluation can approach or exceed the timeout. Hitting the timeout raises a System.QueryException. The standard mitigations are: add Custom Indexes on filtered fields (through Salesforce Customer Support), refactor queries to use indexed fields in WHERE clauses, batch large queries with Batch Apex or LIMIT clauses, and avoid leading wildcards on LIKE filters. For data warehouse-style queries that genuinely scan millions of records, the Bulk API and Bulk API 2.0 are designed for that volume; SOQL is not.
Salesforce Connect timeout and external object queries
Salesforce Connect lets Salesforce orgs expose external system data as External Objects, queried in real time through the underlying integration (OData, REST, or custom). Each query has a 120-second timeout for the external system to respond. Slow external systems hit this limit and return errors to the Salesforce side. The Connect framework also has a 1,000-record max per query, which keeps individual queries responsive but requires pagination for large result sets. Mature Salesforce Connect implementations build defensive query patterns: limit clauses, indexed fields, and graceful error handling when the timeout fires. For external systems that cannot respond within the timeout, consider Data Replication (copying the data into Salesforce on a schedule) instead of live federation through Salesforce Connect.
Diagnosing and preventing timeouts in production
When timeouts surface in production, the root cause is usually one of: a hot record (one record with thousands of related records that triggers a cascading query), a runaway loop (an unbounded recursion or a poorly-written nested iteration), a slow external endpoint (the external system is degraded), or a missing index (a frequently-filtered field never got a Custom Index added). Diagnose through the Setup Debug Logs, the Event Monitoring API (if licensed), and the Setup Optimizer reports. Each timeout type has its own debug pattern: Apex CPU timeouts show up in the debug log as System.LimitException; callout timeouts show as CalloutException; SOQL timeouts as QueryException. Mature production runbooks include playbooks for each timeout type so engineers know where to start when alerts fire.
Designing around Salesforce timeouts
Working with Salesforce timeouts well is mostly about designing within the limits rather than fighting them. The four-step routine covers: identify which timeout each operation is subject to, design the operation to fit within that timeout, monitor timeout occurrences in production, and refactor when timeouts become chronic. Each step is preventive engineering; the alternative is reacting to user-facing failures after they accumulate. Mature Salesforce production operations treat timeouts as architectural constraints to plan around, not bugs to work around.
- Identify the relevant timeout per operation
For each operation in your codebase or integration, identify which timeout applies. Synchronous Apex: 10-second CPU. Asynchronous Apex: 60-second CPU (Queueable, Future, Batch). HTTP Callout: 60-second per callout, 120 max. SOQL query: 120-second platform timeout. User session: configurable per profile, default 2 hours. Salesforce Connect external query: 120-second. Document the relevant timeout for each operation in the technical design document. Without this baseline, engineers troubleshoot timeouts without understanding the constraint.
- Design the operation to fit within the timeout
For Apex CPU-bound work, write bulk-safe code that operates on collections rather than single records. Move expensive work to asynchronous execution. Avoid deeply nested loops over large collections. For callouts, set explicit timeouts on every HttpRequest. Use Continuation for long-running synchronous callouts. For SOQL queries, filter by indexed fields, add LIMIT clauses, batch with Batch Apex. For sessions, pick the right timeout for the user audience: shorter for high-security profiles, longer for integration users. Document the timeout-fit decisions in the code or design doc.
- Monitor timeout occurrences in production
Configure Setup, Debug Logs, to capture timeout-relevant log levels for production users. For Event Monitoring-licensed orgs, query the API Performance Event log for slow API requests. Build a dashboard tracking timeout exception counts by class and operation. Set alerts on rising timeout counts; chronic timeouts are leading indicators of bigger problems. Without monitoring, timeouts hide in the noise until they cause customer-visible failures. Schedule a weekly review of timeout metrics in the production operations runbook.
- Refactor when timeouts become chronic
For timeouts that recur despite the design, refactor the operation. Move synchronous work to async. Add Custom Indexes through Salesforce Customer Support. Split large operations into smaller chunks. Replace inefficient SOQL with selective queries. For callouts to slow external services, add retry logic with exponential backoff rather than just longer timeouts. Document each refactor in the change history. For chronic timeouts that defy refactoring, consider whether the workload genuinely fits the Salesforce platform; some workloads belong on a dedicated compute platform with the Salesforce data accessed through APIs.
- Synchronous Apex has a 10-second CPU limit. Move long-running work to asynchronous (@future, Queueable, Batch) where the limit extends to 60 seconds.
- HTTP callouts in synchronous Apex are constrained by both the callout timeout and the overall 10-second CPU limit. Use Continuation when the external service is slow.
- SOQL queries on unindexed fields with LIKE filters can scan the entire object and hit the 120-second timeout. Add Custom Indexes or refactor the query.
- User session timeout interacts with MFA and the security review schedule. Shorter timeouts force more frequent re-authentication; balance security against user friction.
- Salesforce Connect external queries depend on the external system response time. Slow external systems hit the 120-second timeout; consider Data Replication instead for genuinely slow sources.
Trust & references
Straight from the source - Salesforce's reference material on Timeout.
- Apex Governor LimitsSalesforce Developer Docs
- Apex Callout TimeoutsSalesforce Developer Docs
- Session SettingsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Timeout?
Q2. Why do they exist?
Q3. What's the callout timeout?
Discussion
Loading discussion…