API documentation examples: how to write requests, responses and errors developers trust

Quick answer: Every endpoint in your API docs should have a complete, runnable request (method, URL, headers, auth and body), realistic and consistent sample data, the full success response with its status code, at least one example for each error it can return, and an automated check that keeps the examples in sync with the real API.

Ask developers how they learn a new API and most give the same answer: they skip the prose, find an example, and change it until it works. That makes examples the most-read part of your documentation — and, too often, the least maintained.

This guide covers how to write request and response examples that are complete, realistic and still correct six months after you publish them.

Start every endpoint with a complete request

A complete example includes everything needed to make the call: method, full URL, required headers, authentication and body. A reader should be able to paste it into a terminal, substitute their own key and get a real response. Partial examples that drop headers "for brevity" are one of the most common causes of support tickets.

curl -X POST https://api.example.com/v1/invoices \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9f5a-1d2e3f4a5b6c" \
  -d '{
    "customer_id": "cus_8XkP2",
    "currency": "eur",
    "items": [{ "description": "Pro plan", "amount": 4900, "quantity": 1 }]
  }'

Notice the deliberate choices:

• The key comes from an environment variable ($API_KEY), so readers never paste a real key into a document, a ticket or a screenshot.
• Important optional headers appear by default. Including Idempotency-Key teaches safe retries without a separate lecture.
• The body is formatted across lines, so it is easy to read and edit.

Show the raw HTTP too

curl is popular but not universal. A raw HTTP version is language-neutral and makes every header explicit:

POST /v1/invoices HTTP/1.1
Host: api.example.com
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9f5a-1d2e3f4a5b6c

If you offer SDKs, add tabs for the two or three most-used languages — generated from the same source so they never disagree.

Use realistic, consistent sample data

Values like "string", "foo" and 123 tell the reader nothing about format or meaning. Realistic values teach the shape of the data without a word of explanation:

Field	Unhelpful	Helpful
ID	"id"	"cus_8XkP2" (real format, with prefix)
Timestamp	"date"	"2026-10-22T09:30:00Z" (ISO 8601 with time zone)
Money	49.0	4900 plus a note: amounts are in cents
Email	"string"	"ada@example.com"
Enum	"status"	"draft", with the full list of values documented

Keep sample data consistent across the whole documentation. If the customer created in "Create a customer" is cus_8XkP2, use that same ID when creating an invoice and listing payments. Readers follow docs like a story, and a consistent cast of objects makes the relationships between endpoints obvious.

Show the whole response, then explain what matters

Show the full response for the primary example, including the status code and any headers the client must handle — a Location header on 201 Created, pagination links, or rate-limit headers.

HTTP/1.1 201 Created
Location: /v1/invoices/inv_3Lm9Q
Content-Type: application/json

{
  "id": "inv_3Lm9Q",
  "status": "draft",
  "customer_id": "cus_8XkP2",
  "currency": "eur",
  "total": 4900,
  "created_at": "2026-10-22T09:30:00Z",
  "due_at": null
}

Then explain the fields that are not self-evident: units (total is in cents), formats, which fields can be null and why (due_at is set when the invoice is finalized), and which values an enum can take.

If a response is very long, show it in full once, in a collapsible block, and use a trimmed version elsewhere — but mark the omission ("…": "12 more fields") so nobody assumes fields are missing.

Document errors as carefully as success

Developers spend more time handling errors than successes, yet many docs show only the happy path. For each endpoint, document the errors it can actually return:

Status	Meaning	What to show
400 Bad Request	Malformed request (invalid JSON, wrong types)	The error body and which part failed
401 Unauthorized	Missing or invalid credentials	How to fix authentication
403 Forbidden	Authenticated, but not allowed	Which permission or scope is needed
404 Not Found	Resource does not exist (or is hidden)	Whether IDs from other accounts return 404
409 Conflict	State conflict or idempotency mismatch	How to resolve it
422 Unprocessable Content	Valid JSON that fails validation	Field-level error details
429 Too Many Requests	Rate limit exceeded	The Retry-After header and limits

The meaning of each status code is defined in RFC 9110, the HTTP semantics standard.

Use one consistent error format

A consistent error envelope makes the error section of your docs short and predictable. RFC 9457, Problem Details for HTTP APIs, defines a standard format you can adopt instead of inventing one:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "currency must be a 3-letter ISO 4217 code",
  "errors": [{ "field": "currency", "code": "invalid_format" }]
}

Whatever format you choose, document every type or error code, what causes it and how to fix it — and link to that page from the error itself, as the type URL above does.

Document pagination, rate limits and idempotency once

Cross-cutting behavior should have its own page with examples, linked from every endpoint that uses it:

• Pagination: show a first page, the cursor or link to the next page, and the last page.
• Rate limits: show the headers that report remaining quota and a 429 response with Retry-After.
• Idempotency: show what happens when the same Idempotency-Key is sent twice — with the same body and with a different one.
• Versioning: show how a client pins a version and what changes between versions.

Keep examples correct over time

Examples rot quietly: a field is renamed, a default changes, an endpoint gains a required parameter. Habits that prevent it:

• Generate examples from real traffic. Record requests and responses from your integration tests against a sandbox and publish those.
• Validate examples against your schema. If you maintain an OpenAPI description, put examples in its examples fields and lint them in CI so a mismatch fails the build.
• Search the docs when you deprecate something. Every example that uses the old field needs updating, not just the reference page.
• Date your changelog and show a before-and-after request whenever behavior changes.

When to use images of requests and responses

Reference documentation should use text code blocks: readers need to copy requests and search responses. Images earn their place elsewhere:

• Landing and overview pages, where a styled request and response pair shows what the API feels like at a glance.
• Changelogs and release posts, where a highlighted new field or endpoint is the news.
• Social posts and slides, where code blocks are not available.
• Tutorials, as a visual anchor beside the copyable text.

For these, the API response image tool formats JSON and adds method and status badges, and the HTTP request generator styles the request line, headers and body. Use placeholder tokens in both — see how to redact secrets in screenshots.

A checklist for every endpoint

1. A complete, runnable request with authentication from an environment variable.
2. Realistic sample data, consistent with the rest of the docs.
3. The full success response with status code and important headers.
4. Explanations of units, formats, nullable fields and enum values.
5. An example for every error status the endpoint can return.
6. Links to shared pages on pagination, rate limits and idempotency.
7. An automated check that the examples still match the API.

Frequently asked questions

What makes a good API documentation example?

A good example is complete enough to run as-is (method, URL, headers, authentication and body), uses realistic data in the real formats, shows the full response with its status code, and is verified automatically so it stays correct.

Should API docs include error response examples?

Yes. Developers spend much of their integration time handling errors. Document every error status an endpoint can return, with the exact response body and how to resolve it.

What is the standard format for API error responses?

RFC 9457, Problem Details for HTTP APIs, defines a standard JSON format with type, title, status and detail fields, served with the application/problem+json content type. Many APIs use it or a similar consistent envelope.

Should I use 400 or 422 for validation errors?

A common convention is 400 for requests that cannot be parsed (malformed JSON or wrong types) and 422 for well-formed requests that fail business validation. Either is acceptable if you apply it consistently and document it.