20.3 API docs: examples, edge cases, and error contracts

Goal: API docs that people can actually use

API docs are most valuable when they define:

• exact request/response shapes,
• error behavior,
• examples that match reality,
• edge cases and limits.

Generic “this endpoint returns a summary” docs are useless. Concrete contracts are useful.

Document contracts first (inputs/outputs)

At minimum, include:

• endpoint + method
• request JSON schema (fields + types)
• response JSON schema (fields + types)
• authentication requirements (if any)
• rate limits and input limits

If you already have JSON schemas in the repo, use them as the source of truth.

Error contracts (status codes and categories)

Document error behavior clearly. For LLM apps, outcome categories matter:

• validation_error: bad input
• timeout: took too long
• rate_limit: throttled
• blocked: refusal/safety outcome
• invalid_output: schema mismatch
• unknown: unexpected failure

Provide a stable envelope so clients can handle outcomes predictably.

Examples that reduce support tickets

Include examples for:

• one happy-path request and response
• one validation error
• one timeout/rate limit scenario
• one blocked/refusal scenario (high-level)
• one invalid output scenario (if applicable)

Examples should match schemas exactly and be validated against tests where possible.

Edge cases to document explicitly

Common edge cases that matter:

• max input size and behavior when exceeded
• timeouts and retry behavior
• idempotency rules (if write actions exist)
• partial results (if supported)
• versioning rules (schema/prompt versions)

Using AI to draft API docs safely

AI can draft API docs effectively if you provide contracts:

• schemas,
• test cases,
• example requests/responses,
• error taxonomy.

Force a rule: “Do not invent fields.” Require “unknown” for missing details.

Where to go next

• 20.4 README quickstart
• 20.5 Changelogs and migration notes