Integration Capacity & Reliability

Your Salesforce API limit is an architecture budget—not a project quota

JSBC Labs12 October 20268 min read

The limit belongs to the org

A new Salesforce integration can pass every functional test and still make the platform less reliable. The problem is often not an incorrect request but the cumulative demand created by middleware, mobile applications, data platforms, backup products, marketing tools, test automation and one-off scripts. Standard API consumption is an org-level constraint, not a private allowance assigned to each project.

The JSBC Labs position is that API capacity must be managed as an architecture budget. A project needs permission to consume part of a shared resource, plus an operating margin for peaks, recovery and future change. Treating the published allocation as a target turns normal growth or an outage-driven resynchronisation into a contest in which unrelated integrations fail together.

Measure the estate before adding demand

Start with evidence from production, not the average daily figure in a design document. Inventory API consumers, owners, authentication identities, interfaces, schedules and business criticality. Measure normal usage, peak windows, seasonal changes and unexplained background demand. Include administrative tools and vendor packages; they often sit outside the programme that is proposing the new integration but consume the same capacity.

Salesforce exposes usage through the REST Limits resource and returns standard API usage in the Sforce-Limit-Info response header. API Usage Notifications can alert administrators when defined thresholds are crossed. Those are platform facts. The architecture judgement is how much headroom the organisation requires for batch overlap, retries, month-end processing, releases and recovery after downtime.

Give integrations explicit budgets

For every material consumer, define an expected steady rate, peak rate, daily envelope and recovery envelope. Record which workload can be delayed, which can be reduced and which supports a time-critical customer or regulatory process. A budget is not merely a chargeback number; it is the input to throttling, alerting, capacity forecasting and incident decisions.

Do not allocate the entire org allowance across named systems. Keep an uncommitted reserve and assign warning thresholds below the failure boundary. Revisit budgets when licences, data volumes, schedules or product behaviour change. If nobody owns the forecast for an integration, its demand will be discovered only through a limit alarm or an affected business process.

Choose the API for the workload

Request efficiency is an architectural choice. Bulk API 2.0 is designed for asynchronous operations on large datasets, while REST composite resources can reduce round trips for related operations. Salesforce documents an important distinction: a regular Composite request counts as one API call, whereas Composite Batch subrequests count against rate limits. Similar names do not imply identical consumption or transaction semantics.

Batching also has trade-offs. Larger units reduce request overhead but can increase latency, memory use, lock contention and the amount of work retried after failure. Bulk jobs improve throughput but introduce asynchronous completion and reconciliation. Select the interface using volume, latency, atomicity, error-isolation and recovery requirements—not simply the API that produced the smallest proof of concept.

Make capacity telemetry part of the client

An integration should not wait for an administrator's email before noticing scarcity. Capture limit information returned by Salesforce, publish usage and remaining capacity to operational monitoring, and correlate it with throughput, latency, errors, retries and backlog depth. The client should know whether demand is rising because the business is busy, a cursor is broken or the same records are being polled repeatedly.

Set alerts on trend and rate of change, not only a single percentage. A low-traffic period can hide a runaway consumer until the next batch window. A healthy dashboard shows demand by integration and use case, forecast exhaustion, deferred work and recovery progress. Org-wide consumption without attribution tells operators that a problem exists while withholding the information needed to act safely.

Backpressure must protect business priorities

When capacity tightens, indiscriminate retries make the incident worse. Use bounded exponential backoff with jitter for transient failures, cap retry age and count, and move exhausted work to a recoverable queue. Circuit breakers should pause a failing dependency rather than allowing many workers to amplify the same fault. Idempotency is essential because delayed and repeated delivery must not duplicate business outcomes.

Define degradation order before an incident. Reference-data refreshes may slow while order capture continues; analytics extraction may pause while service transactions remain available. This is a business policy expressed through technical controls. Without it, the fastest or noisiest client consumes the remaining budget, regardless of importance.

Do not buy capacity before removing waste

Additional entitlement can be the right answer for genuine growth, but it should not conceal avoidable demand. Look for full extracts where change-based integration is appropriate, record-by-record writes that can be batched, repeated describe calls, unselective polling, duplicate retries and schedules that collide. Reduce unnecessary fields and frequency when the consumer does not use the extra freshness or payload.

Optimisation also has a stopping point. Replacing a clear interface with elaborate caching or event choreography can cost more than additional capacity and create new failure modes. Compare the financial and operational cost of entitlement, engineering change and business delay. Efficiency is valuable when it improves the system's economics or resilience—not when it becomes an abstract contest to minimise calls.

Load-test the shared system

A single client's benchmark does not prove that the org has capacity. Test realistic concurrency across interactive traffic, scheduled jobs and other integrations, using representative data volumes and transaction behaviour. Salesforce Well-Architected guidance explicitly recommends API load testing to validate scalability, rate-limit handling and circuit-breaker behaviour under sustained load.

Test recovery as well as steady state. Simulate a downstream outage, allow a backlog to accumulate, then measure whether controlled catch-up protects live operations. Verify throttling, idempotency, queue visibility and operator controls. A solution that meets peak throughput only by consuming all available margin has passed a performance test while failing a reliability test.

Prepare the limit incident runbook

Document how to confirm current consumption, identify the largest contributors, contact owners and slow non-critical workloads. Define the evidence required before disabling a client, because emergency credential changes can interrupt important processes and create a larger reconciliation problem. Include vendor escalation paths and the commands or configuration changes used to adjust worker concurrency safely.

Do not rely on the possibility that Salesforce may temporarily allow requests beyond the stated daily allocation. Official guidance describes that behaviour as conditional, not guaranteed capacity. The runbook should restore controlled operation, preserve failed work and reconcile missed data after the constraint clears. Recovery is complete only when business state is consistent, not when API errors stop.

Govern capacity as a portfolio

Review API demand alongside the integration roadmap. Require new designs to state expected consumption, peak and recovery behaviour, telemetry, owner and degradation policy. Reforecast before migrations, acquisitions, seasonal events and large data programmes. Retire credentials and jobs when integrations are decommissioned so abandoned demand and access do not survive indefinitely.

The practical rule is simple: no integration owns the org's API limit. Each one borrows from a shared reliability budget and must prove that its consumption is visible, efficient and controllable. That turns API limits from an unpleasant platform surprise into an explicit design constraint—and gives the organisation room to grow without making every new connection a risk to the ones already running.