Salesforce REST API Capabilities, Rate Limits & Governor Limits by Edition

TL;DR

• Bottom line: Salesforce REST API (v66.0, Spring '26) handles real-time CRUD for individual records and small batches (<2,000 records); switch to Bulk API 2.0 for anything larger. Daily API call limits vary dramatically by edition.
• Key limit: 100,000 base API calls/24h + per-user additions (Enterprise: +1,000/user; Unlimited: +5,000/user). This pool is shared across REST, SOAP, Bulk, and Connect APIs. [src1]
• Watch out for: Governor limits are per-transaction, not per-API-call — a single API request can trigger Apex code that cascades through 100 SOQL queries, 150 DML statements, and 10,000 DML rows before hitting the wall. [src3]
• Best for: Real-time CRM operations under 2,000 records per request — account sync, opportunity management, custom object CRUD, and composite multi-object operations.
• Authentication: OAuth 2.0 JWT bearer flow for server-to-server (recommended); web server flow for user-context; username-password flow deprecated for production. [src2]

System Profile

This card covers the Salesforce REST API across all major commercial editions (Professional, Enterprise, Unlimited, Performance) and the free Developer Edition. Rate limits and governor limits differ significantly by edition — always check which edition your org runs before designing an integration. This card does not cover Salesforce Marketing Cloud (separate API) or MuleSoft Anypoint (separate product).

API Surfaces & Capabilities

Salesforce exposes multiple API surfaces for different use cases. Choose based on data volume, latency requirements, and direction. [src1, src2]

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Transaction / Governor Limits

These limits apply per Apex transaction — a single API request can trigger Apex code (triggers, flows, process builders) that must stay within these boundaries. This is the #1 area where agents hallucinate. [src3]

Authentication

Authentication Gotchas

• JWT bearer flow requires a connected app with digital certificate — self-signed works for dev, CA-signed for production. [src2]
• Access tokens from JWT flow are org-scoped — all API calls execute with the integration user's permissions and profile. [src2]
• Session timeout is admin-configurable (15 min to 24h) — never hardcode 2 hours. [src2]
• OAuth refresh tokens expire after 90 days of non-use — use JWT bearer flow for unattended integrations. [src4]
• Spring '26: Connected app creation is now disabled by default. Use External Client App feature instead. [src6]

Constraints

• Professional Edition requires API add-on: API access is not included by default. Do not recommend API integrations without confirming the add-on is active.
• Daily API pool is shared: REST, SOAP, Bulk, and Connect API calls all draw from the same daily pool. A heavy Bulk API job can starve real-time REST integrations.
• Governor limits cascade through triggers: A single REST API upsert can fire triggers that share the same 100-SOQL, 150-DML, 10,000-row transaction budget.
• Composite API subrequests count as 1 API call: 25 subrequests consume only 1 from daily quota, but still subject to governor limits per transaction.
• No API for formula field writes: Formula fields, rollup summary fields, and system fields cannot be written via API.
• Sandbox limits differ from production: Sandbox orgs have a fixed 5M API calls/24h regardless of edition.
• API version minimum is v31.0: Versions 21.0-30.0 were retired June 2025. Integrations pinned below v31.0 will fail.
• Platform Events require capacity planning: Standard allocation of 50,000 daily event deliveries is shared between Platform Events and CDC.

Integration Pattern Decision Tree

START — User needs to integrate with Salesforce REST API
|-- What's the integration pattern?
|   |-- Real-time (individual records, <1s latency)
|   |   |-- Data volume < 200 records/operation?
|   |   |   |-- YES --> REST API: SObject Collections (multi-record) or Composite (multi-object)
|   |   |   +-- NO --> REST API with chunking (200-record batches) + async processing
|   |   +-- Need notifications/webhooks?
|   |       |-- YES --> Platform Events or Change Data Capture
|   |       +-- NO --> REST API polling with SystemModstamp filter
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- Data volume < 2,000 records?
|   |   |   |-- YES --> REST API SObject Collections (simpler, no batch overhead)
|   |   |   +-- NO --> Bulk API 2.0 (single job <100K; chunking for >100K)
|   |   +-- Need real-time progress tracking?
|   |       |-- YES --> Bulk API 2.0 (poll job status endpoint)
|   |       +-- NO --> Bulk API 2.0 with completion notification
|   |-- Event-driven (CDC, real-time change tracking)
|   |   |-- Need guaranteed delivery?
|   |   |   |-- YES --> Platform Events with replay (72h retention)
|   |   |   +-- NO --> Streaming API / PushTopics
|   |   +-- Need cross-object change tracking?
|   |       |-- YES --> Change Data Capture
|   |       +-- NO --> Object-specific triggers + Platform Events
|   +-- File-based (CSV import)
|       +-- Use Bulk API 2.0 with CSV upload
|-- Which direction?
|   |-- Inbound (writing to SF) --> check daily API limits + governor limits for triggers
|   |-- Outbound (reading from SF) --> check query row limits (50K/transaction)
|   +-- Bidirectional --> design conflict resolution FIRST (external ID + last-modified wins)
+-- Error tolerance?
    |-- Zero-loss --> implement idempotency (external ID upsert) + dead letter queue
    +-- Best-effort --> fire-and-forget with exponential backoff retry

Quick Reference

Key REST API Endpoints

Step-by-Step Integration Guide

1. Authenticate and obtain access token

Use the JWT bearer flow for server-to-server integrations. Create a connected app in Salesforce Setup, upload your X.509 certificate, and configure pre-authorized profiles. [src2]

# Generate JWT and exchange for access token
curl -X POST https://login.salesforce.com/services/oauth2/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=<your_signed_jwt>"

Verify: Response contains access_token and instance_url

2. Query records with SOQL

Use the query endpoint for structured reads. Always paginate — default page size is 2,000 records. [src2]

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$INSTANCE_URL/services/data/v66.0/query?q=SELECT+Id,Name,Industry+FROM+Account+WHERE+LastModifiedDate+>+2026-01-01T00:00:00Z+LIMIT+100"

Verify: Response includes totalSize, done, and records array

3. Create or update records with upsert

Use external ID upsert for idempotent writes — prevents duplicates on retry. [src2]

curl -X PATCH \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "$INSTANCE_URL/services/data/v66.0/sobjects/Account/External_ID__c/EXT-001" \
  -d '{"Name": "Acme Corp", "Industry": "Technology"}'

Verify: 201 (created) or 204 (updated)

4. Handle pagination for large result sets

When done is false, use nextRecordsUrl to fetch the next page. [src2]

import requests

def query_all(instance_url, access_token, soql):
    headers = {"Authorization": f"Bearer {access_token}"}
    url = f"{instance_url}/services/data/v66.0/query"
    params = {"q": soql}
    all_records = []
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    data = response.json()
    all_records.extend(data["records"])
    while not data["done"]:
        next_url = f"{instance_url}{data['nextRecordsUrl']}"
        response = requests.get(next_url, headers=headers)
        response.raise_for_status()
        data = response.json()
        all_records.extend(data["records"])
    return all_records

Verify: len(all_records) == totalSize

5. Implement error handling and retry logic

Handle 429 (rate limit), 503 (service unavailable), and expired tokens with exponential backoff. [src4]

import time, requests

def sf_api_call(method, url, headers, json=None, max_retries=5):
    for attempt in range(max_retries):
        response = requests.request(method, url, headers=headers, json=json)
        if response.status_code == 429:
            time.sleep(min(2 ** attempt * 2, 60))
            continue
        elif response.status_code == 503:
            time.sleep(min(2 ** attempt * 5, 120))
            continue
        elif response.status_code == 401:
            headers["Authorization"] = f"Bearer {refresh_access_token()}"
            continue
        return response
    raise Exception(f"Max retries exceeded for {url}")

Verify: Function returns valid response and retries on 429/503

Code Examples

Python: JWT Auth + SObject Collections Upsert

# Input:  Salesforce credentials (JWT), list of account records
# Output: Upsert results with success/failure counts
import requests, jwt, time
from datetime import datetime, timedelta, timezone
from cryptography.hazmat.primitives import serialization

class SalesforceClient:
    def __init__(self, consumer_key, username, private_key_path,
                 login_url="https://login.salesforce.com"):
        self.consumer_key = consumer_key
        self.username = username
        self.login_url = login_url
        with open(private_key_path, "rb") as f:
            self.private_key = serialization.load_pem_private_key(f.read(), password=None)
        self.access_token = self.instance_url = None

    def authenticate(self):
        now = datetime.now(timezone.utc)
        payload = {"iss": self.consumer_key, "sub": self.username,
                   "aud": self.login_url,
                   "exp": int((now + timedelta(minutes=5)).timestamp())}
        token = jwt.encode(payload, self.private_key, algorithm="RS256")
        resp = requests.post(f"{self.login_url}/services/oauth2/token",
                data={"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
                      "assertion": token})
        resp.raise_for_status()
        data = resp.json()
        self.access_token = data["access_token"]
        self.instance_url = data["instance_url"]

    def upsert_collection(self, sobject, ext_id_field, records):
        url = (f"{self.instance_url}/services/data/v66.0"
               f"/composite/sobjects/{sobject}/{ext_id_field}")
        resp = requests.patch(url, headers=self._headers(),
                json={"allOrNone": False, "records": records})
        resp.raise_for_status()
        return resp.json()

    def _headers(self):
        return {"Authorization": f"Bearer {self.access_token}",
                "Content-Type": "application/json"}

JavaScript/Node.js: Composite API Multi-Object Operation

// Input:  Salesforce access token, instance URL
// Output: Composite response with all subrequest results
async function compositeOperation(instanceUrl, accessToken) {
  const url = `${instanceUrl}/services/data/v66.0/composite`;
  const body = {
    allOrNone: true,
    compositeRequest: [
      { method: "POST", url: "/services/data/v66.0/sobjects/Account",
        referenceId: "newAccount",
        body: { Name: "Acme Corp", Industry: "Technology" } },
      { method: "POST", url: "/services/data/v66.0/sobjects/Contact",
        referenceId: "newContact",
        body: { FirstName: "Jane", LastName: "Doe",
                AccountId: "@{newAccount.id}" } }
    ]
  };
  const response = await fetch(url, {
    method: "POST",
    headers: { "Authorization": `Bearer ${accessToken}`,
               "Content-Type": "application/json" },
    body: JSON.stringify(body)
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

cURL: Check API Limits

# Input:  Valid access token, instance URL
# Output: Remaining API quota

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$INSTANCE_URL/services/data/v66.0/limits" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); \
  print(f'Daily API: {d[\"DailyApiRequests\"][\"Remaining\"]}/{d[\"DailyApiRequests\"][\"Max\"]}')"
# Expected: Daily API: 95432/100000

Data Mapping

Field Mapping Reference

Data Type Gotchas

• DateTime is always UTC in the API (2026-03-02T14:30:00.000+0000); displays in user timezone in UI. [src2]
• Multi-select picklist fields serialize as semicolon-delimited in API ("Value1;Value2") but comma-delimited in UI. [src2]
• Boolean fields accept true/false (lowercase JSON). Sending "True" (string) or 1 (integer) fails. [src2]
• Lookup fields require 18-character Salesforce ID. 15-char IDs are unreliable in API calls. [src2]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Trigger recursion causes governor limit breach: REST API upsert fires cascading triggers consuming shared SOQL/DML pool. Fix: Implement static boolean flags to prevent trigger re-entry. [src3]
• Bulk API jobs fail on BOM characters: UTF-8 BOM causes first column header rejection. Fix: Strip BOM from CSV; use encoding='utf-8-sig' in Python. [src5]
• OAuth refresh token expires after 90 days: Infrequent integrations lose their token. Fix: Use JWT bearer flow or implement weekly token refresh cron. [src4]
• FLS blocks API access silently: Fields return null instead of error when integration user lacks FLS. Fix: Test with integration user profile; use describe calls to verify. [src2]
• Sandbox refresh resets connected apps: Connected apps may need re-authorization after refresh. Fix: Automate via Metadata API; document post-refresh runbook. [src4]
• Sharing rules restrict record visibility: Integration user may not see all records. Fix: Grant "View All" or "Modify All" on required objects. [src2]

Anti-Patterns

Wrong: Querying all records to detect changes

# BAD -- Fetches entire object, wastes API calls
all_accounts = sf.query("SELECT Id, Name FROM Account")
# Then compare locally... O(n) on every sync

Correct: Use SystemModstamp filter for incremental sync

# GOOD -- Only fetches records modified since last sync
changed = sf.query(
    f"SELECT Id, Name FROM Account "
    f"WHERE SystemModstamp > {last_sync}"
)

Wrong: Individual API calls in a loop

# BAD -- 1,000 API calls for 1,000 records
for record in records:
    sf.Account.create(record)  # 1 API call each

Correct: Use SObject Collections for batch operations

# GOOD -- 5 API calls for 1,000 records (200 per call)
for chunk in chunks(records, 200):
    sf.composite.sobjects.create("Account", chunk)

Wrong: Synchronous callouts inside triggers

// BAD -- Callout in a loop hits 100-callout limit
trigger AccountSync on Account (after insert) {
    for (Account a : Trigger.new) {
        Http h = new Http();
        HttpRequest req = new HttpRequest();
        req.setEndpoint('https://external.api/sync');
        h.send(req);
    }
}

Correct: Collect records, process asynchronously

// GOOD -- Collect IDs, process in @future or Queueable
trigger AccountSync on Account (after insert) {
    Set<Id> accountIds = new Set<Id>();
    for (Account a : Trigger.new) {
        accountIds.add(a.Id);
    }
    AccountSyncService.syncAsync(accountIds);
}

Common Pitfalls

• Sandbox != Production API limits: Sandbox has 5M/day but production may have only 100K. Fix: Use full-copy sandbox with realistic data volumes. [src4]
• Not pinning API version: Defaults to latest; breaks when release changes behavior. Fix: Pin version in base URL (e.g., /services/data/v66.0/). [src2]
• Ignoring field-level security: Works with admin profile, fails with integration user. Fix: Create dedicated permission set; use describe calls. [src2]
• Not handling partial success: SObject Collections with allOrNone: false returns mixed results. Fix: Check each result's 'success' flag individually. [src2]
• Hardcoding org URLs: Legacy hostname redirections removed in Spring '26. Fix: Always use instance_url from OAuth response. [src6]
• Exceeding DML rows in batch triggers: Bulk batch of 10K records + cascading updates exceeds 10K DML rows. Fix: Reduce batch size to 200 when complex triggers exist. [src3]

Diagnostic Commands

# Check API usage / remaining limits
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$INSTANCE_URL/services/data/v66.0/limits" | \
  python3 -c "
import sys, json
limits = json.load(sys.stdin)
for key in ['DailyApiRequests','ConcurrentAsyncGetReportInstances','DailyBulkV2QueryJobs']:
    l = limits.get(key, {})
    print(f'{key}: {l.get(\"Remaining\",\"?\")}/{l.get(\"Max\",\"?\")}')
"

# Test authentication (verify token is valid)
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$INSTANCE_URL/services/data/v66.0/"
# Expected: 200

# Verify object/field accessibility
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$INSTANCE_URL/services/data/v66.0/sobjects/Account/describe" | \
  python3 -c "
import sys, json
obj = json.load(sys.stdin)
print(f'Object: {obj[\"name\"]}, Queryable: {obj[\"queryable\"]}')
for f in obj['fields'][:10]:
    print(f'  {f[\"name\"]}: createable={f[\"createable\"]}')
"

# Monitor Bulk API 2.0 job status
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$INSTANCE_URL/services/data/v66.0/jobs/ingest/$JOB_ID"

Version History & Compatibility

Deprecation Policy: Salesforce supports API versions for a minimum of 3 years (~9 releases). Versions retired in groups: 7.0-20.0 in 2022, 21.0-30.0 in June 2025. Pin your version and upgrade deliberately. [API End-of-Life Policy]

When to Use / When Not to Use

Important Caveats

• Rate limits vary dramatically by Salesforce edition. Developer Edition has only 15,000 API calls/24h and 5 concurrent requests — never use for load testing or production.
• Sandbox API limits (5M/day) differ from production and reset independently. Integration passing in sandbox may hit limits in production.
• The daily API call limit is a soft limit — Salesforce allows exceeding temporarily but will enforce hard block with REQUEST_LIMIT_EXCEEDED if sustained.
• Platform Events and CDC share a combined 50K/day delivery allocation in standard tiers. High-volume event architectures require the add-on license.
• Governor limits (SOQL, DML, CPU) are per-transaction and apply regardless of API used — even Bulk API triggers Apex code subject to governor limits.
• All numbers in this card reflect Salesforce docs as of March 2026 (API v66.0, Spring '26). Always verify against /limits endpoint and current release notes.
• EU instances may have different data residency constraints. Cross-region API calls are allowed but may have additional latency.