A workspace platform's API is well designed but developers repeatedly build integrations that break under real conditions. What is missing from the documentation, and what should be added?

What is usually missing

Reference documentation describes syntax — endpoints, parameters, response shapes. What breaks integrations is semantics and operational behaviour, which reference documentation almost never covers.

The specific gaps:

1. Consistency and freshness guarantees. Is a write immediately visible to a subsequent read? Does search reflect a change instantly or with lag? Developers assume read-after-write and build workflows that fail intermittently at exactly the point where the platform is eventually consistent — and nothing in the documentation told them otherwise.

2. Rate limit mechanics, not just numbers. Is the limit per token, per workspace, per endpoint? Is it a fixed window or a token bucket? What is burst behaviour? What should a client do on a rejection — and is there a Retry-After? "1000 requests per minute" without these answers cannot be built against reliably.

3. Pagination behaviour under concurrent modification. If items change while a client paginates, can it see duplicates or miss items? Most integrations that "lose data occasionally" are hitting this.

4. Error taxonomy with guidance. Which errors are retryable, which are permanent, which indicate a client bug. A developer facing a 500 needs to know whether retrying is correct or harmful.

5. Idempotency semantics. Which operations are safe to retry, how idempotency keys are scoped, how long they are retained, and what happens if the same key arrives with a different body.

6. Webhook delivery characteristics. At-least-once? Ordered? Deduplication key? Retry schedule? These are the most common source of broken integrations, because developers assume exactly-once and ordered by default.

What to add

A behavioural contract section stating the guarantees plainly, including the ones you do not provide. "Search is eventually consistent; expect up to N seconds of lag after a write" prevents an entire class of integration bug and costs one sentence.

Working examples for the hard cases, not the easy ones: paginating a large collection safely, handling a rate limit, retrying idempotently, verifying a webhook signature. The trivial GET example is not where developers struggle.

A changelog that includes behavioural changes, not just schema changes. A latency characteristic or a consistency window that changes silently breaks integrations that were correct.

Sandbox environments that exhibit realistic behaviour — rate limits, eventual consistency, occasional failures. A sandbox that is faster and more consistent than production teaches developers to build integrations that only work in the sandbox.

The principle

Document the guarantees, not just the interface. The interface tells a developer how to make a call succeed once. The guarantees tell them how to build something that keeps working — and every guarantee you leave unstated is one a developer will assume, usually the strongest one.