API Contract Documentation

Use this skill when producing documentation artifacts for Salesforce REST API integrations — versioning policies, error code catalogs, rate limit specifications, and request/response schema documentation. Distinct from API implementation: this skill addresses the documentation layer that consumer teams use to build integrations safely.

---

Before Starting

Gather this context before working on anything in this domain:

• What API version is the integration using? (e.g., v60.0). Is there a risk this version is approaching end-of-life?
• Does the integration use standard sObjects REST API, custom Apex REST (@RestResource) endpoints, or both?
• What are the daily API request limits for this org? (Check /services/data/vXX.0/limits or the Sforce-Limit-Info response header.)
• Is an OpenAPI 3.0 document required? Note: Salesforce's OpenAPI beta covers sObjects REST API only — custom Apex REST endpoints must be hand-authored.

---

Questions to Ask Before Configuring

Ask these before the first line of the contract is written. Each answer becomes a field in the record, and each unasked question is a clause the partner will discover in production instead.

Ask	Why it matters	What a good answer adds
"Which Salesforce API version is this contract pinned to, and who owns the upgrade?"	Versions 21.0–30.0 are retired and unavailable as of Summer '25; a request on a retired version returns 410 GONE, not a warning (REST API Guide, API End-of-Life Policy)	The salesforce_api_version, owner and eol_review_date fields of the contract record
"Is the partner's key our record Id, or their own identifier stored in an External Id field?"	If the external Id matches more than one record, REST API returns 300 and the record is neither created nor updated (REST API Guide, Insert or Update (Upsert) a Record Using an External ID)	The idempotency-key strategy plus a named runbook row for the duplicate-key case
"How many other integrations already draw on this org's 24-hour API allocation?"	The total inbound API request allocation is per org per 24-hour period, not per integration (Developer Limits Quick Reference, Total API Request Allocations) — one partner's retry storm exhausts every other integration's budget	A per-integration request budget in the rate-limit clause, not just the org ceiling
"For each Salesforce errorCode the partner can receive, what does the partner do — retry, alert, or park the record?"	The error response body is an array of error objects carrying message, errorCode and fields; a consumer that reads only the HTTP status discards the reason	One row per errorCode in the error contract, each with a partner-side action
"Does this integration send batches, and is a partial failure acceptable?"	An sObject Collections request that is well formed returns 200 OK even when individual items failed — per-item outcomes live in the errors array (REST API Guide, Upsert Records Using sObject Collections)	The allOrNone decision and an explicit per-row reconciliation step
"Is any endpoint here a custom Apex REST class rather than a standard resource?"	The sObjects OpenAPI beta generates nothing for @RestResource classes, and a custom resource's URL mapping collides silently with another class's (see references/gotchas.md 7)	Which half of the OpenAPI document is generated and which half a human owns
"Who approves a breaking change, and how much notice does the partner get?"	Salesforce notifies customers at least 1 year before support for an API version ends; an internal contract with a shorter notice period is stricter than the platform it runs on	The change-control section: notice period, approver, and the deprecation-notice template

What a proper configuration adds over just doing it: the partner's error handling is derived from the errorCode values Salesforce actually emits rather than from HTTP status alone, retries are idempotent by construction, and the version retirement date is a dated owner-assigned task instead of a 410 GONE incident.

---

Core Concepts

Salesforce API Versioning Policy

Salesforce REST API versioning uses integer version numbers (e.g., v60.0, v61.0). The official policy guarantees:

• A minimum 3-year support window for each released version
• At least 1 year's advance notice before a version is retired
• The /services/data/ endpoint enumerates all currently live API versions with their version, label, and url properties

Grounded status as published in the Summer '26 REST API Developer Guide (API End-of-Life Policy):

Versions	Status
31.0 through 66.0	Supported
21.0 through 30.0	Retired and unavailable as of Summer '25
7.0 through 20.0	Retired and unavailable as of Summer '22

A request against a retired version returns 410 GONE. Before the version is retired, a call against a deprecated version returns a Warning response header with warningCode 299 and a message naming the release in which it will be removed — that header is the only advance signal the runtime gives you, and most HTTP clients drop it. To identify which callers are still on old versions, use the API Total Usage event type.

Calls to the Versions URI (/services/data/) do not count toward the org's API limit and do not require authentication, so an EOL check can run from anywhere.

The Error Contract: Status Codes and the Errors Array

The response body of a failed REST API call is a JSON array of error objects, each carrying the message, the errorCode, and (where applicable) the offending fields:

[
  {
    "fields": ["Id"],
    "message": "Account ID: id value of incorrect type: 001900K0001pPuOAAU",
    "errorCode": "MALFORMED_ID"
  }
]

Status codes the REST API Developer Guide documents (Status Codes and Error Responses) — the ones a contract must name explicitly:

Code	What it means for the contract
300	The external Id matched more than one record. The body contains the list of matching records; nothing was written
304	Content unchanged since the If-Modified-Since value the caller sent
400	The JSON or XML body contains an error
401	The session ID or OAuth token expired or is invalid
403	Refused. If errorCode is REQUEST_LIMIT_EXCEEDED, the org's API request allocation is exhausted
404	Resource not found — a bad URI or a sharing issue, which the status alone cannot distinguish
405	Method not allowed for that resource
409	Conflict with the current state — check the API version is compatible with the resource
410	The resource has been retired or removed
412	A precondition in the request headers (for example If-Unmodified-Since) was not satisfied
414 / 431	The URI, or the URI plus headers, exceeds the 16,384-byte limit
415	The request entity is in a format the method does not support
428	The request was not conditional; add a conditional request header
500 / 502 / 503	Platform error, Salesforce Edge could not reach the instance, or the server is unavailable

Note what is not in that table: HTTP 429 is not listed as a REST API status code in the guide's Status Codes and Error Responses section. Treat 429 as something a gateway, proxy or middleware layer in front of Salesforce may return, and say so in the contract rather than attributing it to the platform. UNVERIFIED (2026-09-04): the REST API Developer Guide's status-code table does not document 429; whether any Salesforce edge tier emits it is not established by the guides available here.

Rate Limits and the Sforce-Limit-Info Header

Salesforce API request limits are tracked in a rolling 24-hour window. Two indicators:

1. Sforce-Limit-Info response header — Returned on every REST API request except calls to the Versions URI (/). The documented example carries two counters: Sforce-Limit-Info: api-usage=10018/100000; api-bursts=1/750. The first number in api-usage is calls used, the second is the org's limit. Consumer systems should log this header to track consumption trends.
2. /services/data/vXX.0/limits resource — Returns the current org's limits across all limit types including DailyApiRequests. Poll this endpoint to proactively detect approaching exhaustion.

When the daily limit is exhausted, the response is HTTP 403 with error code REQUEST_LIMIT_EXCEEDED. The same exception code is also returned when the concurrent limit on long-running requests is exceeded — a distinct condition documented in the Developer Limits Quick Reference (Concurrent API Request Limits): requests lasting 20 seconds or longer are capped at 5 for Developer Edition and Trial orgs, 25 for production orgs and sandboxes, with no limit on requests shorter than 20 seconds.

The exact numeric daily limit depends on the org edition and add-on licenses — it is NOT a fixed published value. The Developer Limits Quick Reference states the total as 100,000 + (number of licenses × calls per license type) + purchased API Call Add-Ons for Enterprise, Unlimited and Performance Editions, and a flat 15,000 for Developer Edition. Retrieve the org's actual figure from the /limits resource rather than computing it.

Batching and What Counts as One Call

Resource	Contract-relevant limit
Composite (/composite)	Up to 25 subrequests; the entire series counts as a single call toward API limits
Composite graphs	Up to 500 subrequests, and each graph either completes entirely or not at all
Composite tree (/composite/tree)	Up to 200 records across all trees, up to five records of different types, trees up to five levels deep; the entire request counts as a single call
sObject Collections	Up to 200 records per request; the entire request counts as a single call. Available in API version 42.0 and later (46.0 and later for upsert)
API timeout	10 minutes for REST and SOAP calls except query calls; for Composite resources the timeout applies to the whole composite request, not to each subrequest

OpenAPI 3.0 for sObjects REST API (Beta)

Salesforce provides a beta OpenAPI 3.0 document generator for the sObjects REST API (standard Create/Read/Update/Delete operations on SObjects). Access via:

GET /services/data/vXX.0/sobjects/{SObjectName}/describe/openapi3_0

Critical limitation: This beta feature generates OpenAPI specs only for standard sObjects REST endpoints. It does NOT cover:

• Custom Apex REST endpoints (@RestResource classes)
• Composite API resources (/composite, /composite/batch)
• Connect REST API (Chatter, Experience Cloud)

Custom Apex REST endpoints must have their request/response contracts hand-authored using OpenAPI 3.0 or another specification format. See references/worked-examples.md § 2 for a hand-authored excerpt.

---

Common Patterns

Pattern: API Versioning Policy Documentation

When to use: When onboarding a new integration consumer team or producing architecture documentation for an existing integration.

How it works:

1. Enumerate live API versions: GET /services/data/ — returns an array of available versions.
2. Record the integration's pinned version and its label from the response.
3. Document the retirement policy: 3-year support window, 1-year advance notice.
4. Add a recurring review step (quarterly) to check the Salesforce EOL notice list: check Release Notes and api_rest_eol.htm with each seasonal release.
5. Define the version upgrade SLA for the integration team (e.g., "upgrade within 6 months of deprecation notice").

Pattern: Rate Limit Documentation and Monitoring

When to use: When consumer teams need to understand how to avoid API limit exhaustion during bulk operations or high-frequency integrations.

How it works:

1. Document the daily limit retrieval method: GET /limits returns DailyApiRequests.Max for the org.
2. Establish a monitoring pattern: log the Sforce-Limit-Info: api-usage=X/Y header from every response and alert when X/Y > 80%.
3. Document the error: HTTP 403 REQUEST_LIMIT_EXCEEDED means daily limit is exhausted; a 429 from a fronting gateway is transient throttling. These have different recovery patterns: 403 requires waiting until the 24-hour window resets; a gateway throttle requires exponential backoff retry.
4. For bulk operations, recommend Bulk API 2.0 which has a separate request budget from the REST API limit.

Pattern: The Contract Record as the Unit of Work

When to use: Whenever more than one endpoint or more than one direction exists — which is nearly always.

Write one record per endpoint per direction. An inbound order push and an outbound account-status read are two contracts even when the same partner and the same Named Credential are involved: they have different auth principals, different error surfaces and different idempotency keys. The filled record in references/worked-examples.md § 1 is the shape; scripts/check_api_contract_documentation.py is what tells you it is complete. Each finished record is a catalog row for agents/integration-catalog-builder/AGENT.md (§ Output Contract, "Catalog").

---

Decision Guidance

Situation	Recommended Approach	Reason
Documenting standard CRUD API endpoints	Use sObjects OpenAPI beta + hand-authored supplement	Beta covers CRUD; manually document composite and custom endpoints
Documenting custom Apex REST endpoints	Hand-author OpenAPI 3.0 spec	Beta does not cover @RestResource endpoints
Consumer needs rate limit ceiling	Retrieve from /limits dynamically, not from documentation	Limit varies by org edition and license
Integration hitting REQUEST_LIMIT_EXCEEDED	Wait for 24-hour window reset; switch to Bulk API 2.0 for bulk ops	Daily limit resets on rolling 24-hour basis
Checking if API version is near retirement	Check api_rest_eol.htm with each seasonal release	EOL list is updated per Salesforce release cycle
Partner needs at-most-once write semantics	Upsert on an External Id field, not POST on a record Id	The external Id makes the retry idempotent; a repeated POST creates a duplicate
Partner sends 150 records per message	sObject Collections (200-record cap, one API call) rather than 150 single-row calls	Reduces the org allocation draw by two orders of magnitude for the same payload
Deciding which integration pattern the contract even describes	Read standards/decision-trees/integration-pattern-selection.md first	This skill documents the chosen pattern; it does not choose it

---

Recommended Workflow

1. Inventory endpoints, one record per endpoint per direction. Copy the skeleton from templates/api-contract-documentation-template.md; the filled equivalent is references/worked-examples.md § 1.
2. Pin and justify the API version. GET /services/data/ (unauthenticated, does not count toward the allocation) lists every live version. Set salesforce_api_version and eol_review_date; cross-reference integration/api-versioning-strategy for the sunset policy the org has adopted.
3. Fill the error contract before anything else. One row per errorCode the partner can receive, each mapped to a partner-side action. Work from the status-code table in § Core Concepts and the catalogue in references/worked-examples.md § 3 — not from the HTTP status alone.
4. State the idempotency key and the rate-limit clause. Decide External Id upsert vs. record Id, and give this integration a request budget inside the org allocation. Read references/gotchas.md gotchas 1, 4, 5 and 6 before writing these two clauses.
5. Hand-author the OpenAPI excerpt for every Apex REST resource. references/worked-examples.md § 2 shows the shape including the Salesforce error schema; the class itself is apex/apex-rest-services territory, not this skill's.
6. Lint the record. python3 scripts/check_api_contract_documentation.py --file <contract>.yaml (or --manifest-dir <dir> for a set). It exits 1 on a missing owner or review date, an unmapped errorCode, an absent retry policy, or an out-of-set direction/auth/status.
7. Publish, then hand off. File the record where agents/integration-catalog-builder/AGENT.md § Output Contract expects its catalog row, and put eol_review_date on someone's calendar — see references/worked-examples.md § 5 for the deprecation notice you will eventually send.

---

Review Checklist

Run through these before marking work in this area complete:

• API version documented and checked against EOL list
• Daily API limit retrieved from /limits resource (not hardcoded)
• Error code catalog includes 300, 400, 401, 403 (REQUEST_LIMIT_EXCEEDED), 404, 409, 410, 500
• Every errorCode row states the partner-side action, not just the meaning
• Sforce-Limit-Info header monitoring pattern documented
• OpenAPI spec covers all endpoints (standard + hand-authored for Apex REST)
• Idempotency key named (External Id field API name, or an explicit "not idempotent" statement)
• Version upgrade SLA defined for integration team
• No hardcoded rate limit numbers that could become stale
• check_api_contract_documentation.py exits 0 against the finished record

---

Salesforce-Specific Gotchas

1. Fabricating specific numeric rate limits is dangerous — API request limits are NOT a fixed universal number. They vary by org edition, add-on licenses, and Salesforce's adjustments. Never document a specific hardcoded number. Always reference the /limits resource or the developer limits quick reference cheatsheet.

2. OpenAPI beta does not cover custom Apex REST — Teams often assume the OpenAPI endpoint generates documentation for all their APIs. Custom @RestResource endpoints have no auto-generated spec. They must be hand-authored.

3. SLA uptime commitments are not in developer docs — API SLA percentages (uptime, latency) are in trust.salesforce.com and Order of Service agreements, not in the developer documentation. Do not document SLA percentages from developer docs — they do not exist there.

4. REQUEST_LIMIT_EXCEEDED (403) means two different things — it is returned both when the org's 24-hour allocation is exhausted and when the concurrent long-running-request limit is exceeded. The first needs the window to reset; the second clears as soon as in-flight requests finish. A contract that describes only the first leaves the partner retrying the wrong way.

The full set, with What happens / When it occurs / How to avoid, is in references/gotchas.md.

---

Output Artifacts

Artifact	Description
API contract record (YAML)	One per endpoint per direction: auth, version, schema, error contract, idempotency, rate limit, owner, review date
API versioning policy document	Pinned version, support window, EOL check cadence, upgrade SLA
Rate limit specification	DailyApiRequests.Max from /limits, Sforce-Limit-Info monitoring pattern
Error code catalog	All HTTP status codes the integration must handle with recovery guidance
OpenAPI 3.0 spec	Generated for sObjects endpoints, hand-authored for Apex REST
Deprecation notice	Dated partner-facing notice tied to the version retirement schedule

---

Reference Files

File	Read it when
references/worked-examples.md	You need a filled-in contract record, an OpenAPI excerpt, a contract test or a deprecation notice to copy and adapt
references/gotchas.md	Before writing the error, rate-limit, idempotency or versioning clause of any contract
references/examples.md	You want the two narrative walkthroughs — version retirement risk, and limit exhaustion during a nightly batch
references/llm-anti-patterns.md	Reviewing a contract document an AI assistant drafted
references/well-architected.md	Justifying the contract to an architecture review, or citing the sources behind a claim

---

Related Skills

• apex/apex-rest-services — Use for implementing custom Apex REST endpoints (@RestResource) — the implementation layer this skill documents
• integration/rest-api-patterns — Use for the request shapes themselves (composite, sObject Collections, query); this skill documents them, that skill designs them
• integration/api-versioning-strategy — Use for the org's sunset and contract-evolution policy that this skill's salesforce_api_version field must comply with
• integration/named-credentials-setup — Use for the endpoint and principal record this skill's auth field names
• integration/api-governance-and-rate-limits — Use for governing the shared 24-hour allocation across integrations, once more than one contract exists
• integration/oauth-flows-and-connected-apps — Use for OAuth flow selection and Connected App configuration for API consumers
• integration/api-led-connectivity — Use for designing the API layer architecture before documenting individual endpoints
• admin/integration-pattern-selection — Use before this skill, to choose the pattern the contract will describe
• admin/integration-admin-connected-apps — Use for the Connected App inventory the contract's auth field points into
• data/external-id-strategy — Use for choosing the External Id field that becomes the contract's idempotency key
• devops/api-version-management — Use for upgrading the API version on your own Apex, LWC and sfdx-project.json