Skip to content

PranavNagrecha/AwesomeSalesforceSkills / skills/admin/api-contract-documentation

api-contract-documentation

Verified

Produce or review API contract documentation for Salesforce integrations: versioning policy artifacts, request/response schema specs, error code catalogs, rate limit documentation, OpenAPI generation for sObjects. Trigger keywords: Salesforce API versioning policy, API end-of-life policy, document API endpoints, REST API rate limits, OpenAPI sObjects, API contract record, error contract, errorCode catalog, 410 GONE retired API version, HTTP 300 external ID upsert, idempotency key, deprecation notice, composite subrequest limit. NOT for building the endpoint or writing the Apex REST service — use apex/apex-rest-services. NOT for upgrading the API version on your own Apex, LWC or sfdx-project.json — use devops/api-version-management.

references/llm-anti-patterns.md

View on GitHub
# LLM Anti-Patterns — API Contract Documentation

Common mistakes AI coding assistants make when generating or advising on Salesforce API contract documentation.

---

## Anti-Pattern 1: Fabricating Specific Numeric Rate Limits

**What the LLM generates:** "Salesforce allows 15,000 API calls per day for Enterprise Edition."

**Why it happens:** LLMs have seen various Salesforce limit numbers in training data without knowing they are dynamic, org-specific values.

**The correct pattern:** API request limits vary by org edition and add-on licenses. Never document a hardcoded number. Always retrieve the actual limit from `GET /services/data/vXX.0/limits` (returns `DailyApiRequests.Max`) or reference the Salesforce Developer Limits Quick Reference cheatsheet.

**Detection hint:** Any specific numeric daily API limit in documentation without a source from the `/limits` resource or official cheatsheet is unverified and potentially wrong.

---

## Anti-Pattern 2: Assuming OpenAPI Beta Covers All APIs

**What the LLM generates:** "Use the Salesforce OpenAPI beta endpoint to generate documentation for all your APIs including custom Apex REST."

**Why it happens:** LLMs generalize the OpenAPI generator to all Salesforce APIs without knowing the scope limitation.

**The correct pattern:** The Salesforce OpenAPI beta covers only standard sObjects REST API (CRUD operations). Custom Apex `@RestResource` endpoints, Composite API, and Connect REST API require hand-authored specs.

**Detection hint:** Any recommendation to use the OpenAPI beta for custom Apex REST endpoint documentation is incorrect.

---

## Anti-Pattern 3: Treating 403 REQUEST_LIMIT_EXCEEDED the Same as 429 Throttling

**What the LLM generates:** "Implement exponential backoff retry on all 4xx errors including 403."

**Why it happens:** LLMs generalize error handling patterns without knowing the semantic difference between 403 (resource exhausted) and 429 (transient throttle).

**The correct pattern:** HTTP 403 `REQUEST_LIMIT_EXCEEDED` means the 24-hour daily budget is exhausted. Exponential backoff will not help until the rolling window resets. Document these as separate error conditions with separate recovery procedures.

**Detection hint:** Any error handling guide that applies the same retry logic to 403 and 429 is conflating two different error conditions.

**Sharper still:** the REST API Developer Guide's Status Codes and Error Responses table does not list 429 at all, so a contract that attributes 429 to Salesforce is describing the gateway or middleware in front of it. And `REQUEST_LIMIT_EXCEEDED` itself covers two conditions — the exhausted 24-hour allocation *and* the concurrent long-running-request cap — which need different recoveries. See `references/gotchas.md` gotchas 3 and 4.

---

## Anti-Pattern 4: Documenting SLA Percentages from Developer Docs

**What the LLM generates:** "Salesforce guarantees 99.9% uptime for REST API calls."

**Why it happens:** LLMs extrapolate SLA numbers from general cloud service expectations or training data about other platforms.

**The correct pattern:** Salesforce API SLA uptime and latency commitments are in trust.salesforce.com and Order of Service agreements — not in developer documentation. Do not document SLA percentages based on developer docs; reference trust.salesforce.com instead.

**Detection hint:** Any SLA percentage cited from developer documentation is unverified. SLA commitments require checking trust.salesforce.com and the Order of Service.

---

## Anti-Pattern 5: Not Including the Sforce-Limit-Info Header in Monitoring Design

**What the LLM generates:** API contract documentation that describes rate limits in text but does not include guidance on the `Sforce-Limit-Info` response header.

**Why it happens:** LLMs describe limits as static documentation rather than as runtime observability signals.

**The correct pattern:** The `Sforce-Limit-Info: api-usage=X/Y` header is present on every REST API response and provides real-time consumption visibility. Consumer teams must log this header and alert when X/Y exceeds a threshold (e.g., 80%). Documentation must include the header format and monitoring guidance.

**Detection hint:** API rate limit documentation that does not include the `Sforce-Limit-Info` header is missing the operational monitoring requirement.

---

## Anti-Pattern 6: Modelling the Salesforce Error Body as a Single Object

**What the LLM generates:** An OpenAPI error schema (or a partner-side DTO) shaped as `{ "message": string, "errorCode": string }`, and handler code that reads `response.errorCode`.

**Why it happens:** Most REST APIs return one error object per failure, so the LLM applies the majority shape. Salesforce returns a JSON **array** of error objects — the guide's own examples are `[{ "fields": ["Id"], "message": "...", "errorCode": "MALFORMED_ID" }]` and `[{ "message": "The requested resource does not exist", "errorCode": "NOT_FOUND" }]`.

**The correct pattern:** Type the error as an array of `{ message, errorCode, fields }` and make the handler iterate. See the `SalesforceErrors` schema in `references/worked-examples.md` § 2.

**Detection hint:** Any error schema whose `type` is `object` rather than `array`, or any handler that dereferences `errorCode` without indexing first. This bug survives UAT because most single-cause failures still parse if the client is lenient; it surfaces on the first multi-field validation failure.

---

## Anti-Pattern 7: Treating a 200 from a Batch Resource as "All Rows Saved"

**What the LLM generates:** Reconciliation logic — or a contract clause — whose success criterion is `if (response.status == 200) markAllDelivered()` for an sObject Collections or composite request.

**Why it happens:** For single-record REST calls the HTTP status genuinely is the outcome, and the LLM generalises. For sObject Collections it is not: if the request is well formed the API returns `200 OK`, and per-item outcomes live in the response, where each item carries a `success` flag and an `errors` array.

**The correct pattern:** Require per-row reconciliation in the contract — count `success: true` items against items sent — and record the `allOrNone` decision explicitly, because `allOrNone: true` converts silent partial loss into a whole-batch rollback, which is a business choice rather than a default.

**Detection hint:** Any batch integration whose monitoring dashboard tracks HTTP status codes and nothing else. Green for weeks, then a reconciliation gap nobody can date.

---

## Anti-Pattern 8: Documenting a Hardcoded Host Instead of the Named Credential

**What the LLM generates:** An outbound contract whose `endpoint` is `https://partner.example.com/v1/orders`, matching what the Apex looks like it calls.

**Why it happens:** The LLM resolves `callout:Northwind_OMS/v1/orders` to what it believes the URL is, because a concrete URL reads as more informative than a credential name.

**The correct pattern:** Document the `callout:<NamedCredential>/<path>` form as the contract endpoint and let the Named Credential record own the host. Apex resolves the host at runtime, so repointing the credential retargets every caller with no code diff and no failing test — a hardcoded host in the document is guaranteed to go stale silently.

**Detection hint:** An outbound contract that names a hostname but no Named Credential. Cross-check against `agents/integration-catalog-builder/AGENT.md`, which inventories the credential records that actually decide the host.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall