Skip to content

Docsio v2 is out

See changelog
← Docsio Research

API documentation · Research synthesis

What should API error docs tell you beyond the status code?

Why 403, 404 and 500 do not always tell developers what to do next. A source-based guide to error identity, safe retries, uncertain outcomes and support evidence.

By Docsio Research15 min read

An error reference is useful when a developer can choose a safe next action. HTTP status, a stable error identity, relevant context and the operation’s outcome each answer different questions. This report compares standards with provider guidance and proposes a practical way to document recovery without guessing or repeating work.

Key findings

  • A status code does not uniquely identify the cause or the right recovery action. Provider-specific reasons and headers matter.

  • Machine-readable error identity should remain separate from explanatory prose and information intended for support.

  • An error response or missing response does not always prove that an operation had no effect. Retry instructions must address uncertainty.

  • Useful error documentation includes stopping conditions, verification and escalation, not just an example response.

How we researched this

We reviewed seven primary sources on November 16, 2026: two HTTP standards and official guidance from GitHub, Stripe, Google Drive and Microsoft Graph. The sources were selected for contrasting error and recovery behavior, not as a representative sample or a vendor ranking. We independently opened the original pages after model-assisted discovery. Numbers describe protocol codes or documented policy, not measured error rates. The decision model, example error card and test matrix below are our proposed documentation practices. We did not run a reliability benchmark or induce errors in customer systems.

An error reference should support a decision

Consider a developer trying to create an export. The request fails, and the documentation explains that a server error means something went wrong. That definition may be correct, but it does not answer the question now blocking the integration: should the developer retry, inspect an existing job, change the request or contact support?

Our proposed unit of documentation is an error decision, rather than a status-code definition. It connects an observable response to the next action and the evidence needed to judge its result. The distinction matters most when a retry could create another resource or repeat an external effect.

QuestionInformation the reader needsWhat an incomplete reference leaves unclear
What happened?HTTP response plus a documented error identityWhether several causes share the same status
What can I change?Relevant input, permission, quota or state conditionWhether repeating the request can help
What might already have happened?Operation-specific outcome guaranteesWhether the original attempt created anything
What should I do next?Conditional recovery instructionsWhether to retry, reconcile or escalate
How do I know it worked?An observable completion conditionWhether another successful response is enough

This is an editorial framework, not an additional wire format. An API can use it with an existing response schema. The aim is to make the implementation's contract legible, not to add fields that the server does not actually supply.

Start with one important operation and walk through the unhappy path as a reader. If the page says “try again,” identify the preconditions that make another attempt safe. If it says “contact support,” identify what support needs and what the reader should omit. If it says “check permissions,” link to the permissions for this endpoint and explain whose identity is being evaluated.

A generic status appendix can remain useful for orientation. It should not be the only destination for an error link when the recovery decision depends on details of the endpoint, credentials or SDK.

The same status can lead to different actions

GitHub documents a deliberate 404 response for improperly authenticated requests to private resources, avoiding confirmation that a private repository exists. Its rate-limit guidance also permits 403 or 429, with headers and the response helping determine the appropriate wait. That response to an improperly authenticated request does not establish that the private resource was deleted, and a 403 is not always fixed by adding permissions. GitHub

Google Drive provides another contrast within one API. Its 403 examples include both insufficient file permissions and a per-user rate limit. Those reasons call for different remedies. Google Drive

Provider-specific observationUnsafe shortcutBetter documentation direction
GitHub can conceal private-resource existence with 404Recreate the allegedly missing resourceCheck the documented authentication and access conditions
GitHub rate limits can produce 403 or 429Treat every 403 as a permanent authorization failureInspect the documented rate-limit evidence
Drive 403 can identify insufficient file permissionsRetry until it succeedsCheck write access for the relevant file
Drive 403 can identify a per-user rate limitReplace the user's credentialsFollow the reason-specific quota and backoff guidance

The observations come from the two provider guides above. The unsafe shortcuts and suggested documentation directions are our analysis, not reports of measured incidents. They illustrate why an error table needs a cause column, not just a code and a sentence.

A useful decision tree also preserves uncertainty. If the service intentionally avoids revealing whether a resource exists, the docs should not teach a workaround that discloses it. Explain the checks an authorized caller can make, while keeping the response's privacy boundary intact.

Avoid expanding access indiscriminately as a troubleshooting step. For example, a page should help readers identify the correct resource owner and credential type before suggesting a permission change. That is more actionable than “give the token more permissions,” and it creates a clear point at which the developer can stop and ask an administrator for help.

Separate machine identity from explanation

RFC 9457 defines Problem Details, a standard representation for HTTP API problems. Its type URI identifies the problem; title and detail provide human-readable explanation, while instance identifies an occurrence. The body’s status is advisory; the origin server must generate a matching HTTP response status. Clients should not parse detail for structured information and must ignore unrecognized problem-detail extension members. The format is not required for every error: existing application formats or an HTTP status alone can be appropriate. RFC 9457

Microsoft Graph makes a similar distinction in its own format. Applications can depend on error codes, should use the most specific nested code they understand, and should not depend on message text. Its developer-facing messages should not be displayed directly to end users. This does not imply Graph implements Problem Details. Microsoft Graph

For documentation owners, the practical task is to define the compatibility contract around whatever identifiers the API actually returns. Tell developers which fields are intended for branching and which are there to explain an individual occurrence. Do not encourage copying an English sentence into a string comparison just because it appears stable in one example.

Our recommended review asks three separate questions:

  1. Can the machine select an appropriate handling path without interpreting prose?
  2. Can the developer understand the cause without guessing the meaning of an opaque identifier?
  3. Can support locate the occurrence without requiring the reader to send sensitive payloads?

One field rarely answers all three well. A stable error code may need a linked explanation. A readable explanation may include changing values. A correlation identifier may be useful only to the service operator. Name those roles explicitly.

Also describe behavior for unfamiliar errors. A client written today may encounter a new reason tomorrow. The documentation should offer a conservative fallback that preserves evidence and avoids repeating a risky operation indefinitely. A comprehensive list of current codes is not a guarantee that no additional code can ever appear.

If the API changes an error identity, review the effect on integrations as well as the rendered page. Readers may have written handling logic based on the documented value. A prettier label is not necessarily a harmless change to that contract.

Retry timing and retry safety are different questions

HTTP Semantics distinguishes idempotent operations from operations that cannot safely be repeated without additional knowledge. RFC 9110 advises against automatic retry of a non-idempotent method unless the client knows its semantics are idempotent or can determine that the original request was not applied. It also defines Retry-After as either an HTTP date or a delay in seconds. RFC 9110

A delay therefore answers when another attempt might be appropriate; it does not, by itself, establish whether another attempt is safe. That second decision needs the operation's contract.

Stripe's retry and replay behavior is version-sensitive. Its advanced guidance explicitly treats a 500 outcome as indeterminate: side effects may have occurred. It advises resolving the original outcome before using a new idempotency key, using object inspection, its Dashboard and webhook evidence as applicable. For API v1, the cached response stays unchanged during reconciliation. The guide limits retries of an unresolved operation to the first 24 hours using the same key and parameters; beyond that, it directs readers to reconcile rather than retry. This is Stripe-specific guidance, not a universal rule for every payment API. Stripe advanced handling

For Stripe API v1, the idempotency reference says retries return the first saved response after execution begins, including 500 errors. Keys may be removed after they are at least 24 hours old; reuse after removal can execute a new request. Parameter mismatches are rejected. Validation failures before execution are treated differently. The reference explicitly distinguishes API v2 behavior, so these v1 rules must not be applied to every Stripe API. Stripe idempotency

Our recommendation is to document retries as a conditional procedure. State what evidence permits repetition, whether an operation identifier or key must be reused, what must remain identical, and when the documented protection stops applying. If an SDK retries automatically, specify the relevant SDK version and configuration instead of assuming the reader is making one network attempt per function call.

For an uncertain outcome, provide a reconciliation path. The reader needs to know how to find the operation they may already have started and how to distinguish “not found yet” from “definitely not created.” If the API cannot settle that distinction immediately, say what should happen while the outcome remains unknown.

Do not turn a recovery example into a hidden second creation attempt. A fresh identifier, changed request or expired protection window can change the meaning of the retry. The docs should explain that boundary before offering executable code.

A worked error card for an uncertain export

The following is a hypothetical design exercise for an export API. It is not a description of Docsio, a provider reviewed here, or an existing implementation. Its purpose is to show the information a documentation owner should obtain from the engineering team before writing recovery instructions.

Suppose an API accepts a request to create a report export, but the caller loses the connection before receiving the result. The docs should not invent certainty by assigning a convenient HTTP status to a response that never arrived. Instead, the error card can explain the ambiguous condition and a verified recovery route.

Card fieldExample documentation content to confirm with engineering
ConditionThe client did not receive a conclusive response to a create-export attempt
OutcomeThe export might or might not exist; absence of a response does not settle this
CorrelationUse the operation identifier recorded before sending the original request
First checkLook up the original operation using the supported lookup mechanism
If still processingObserve that operation rather than creating another
If confirmed absentFollow the endpoint's documented retry and identity rules
If unresolvedPreserve the attempt metadata and escalate through the stated support path
VerificationConfirm the intended export exists and is associated with the original operation

This card is useful only if the API actually supports its lookup and correlation steps. If it does not, the correct result of the exercise is an implementation gap, not a fictional endpoint added to the docs.

Notice what is missing from the example: there is no universal number of retries, no invented retention period, and no promise that a timeout means failure. Those are facts the service must supply. The author can make the unresolved questions visible without filling them with reassuring guesses.

For a real product, add the supported SDK behavior, exact lookup fields, relevant retention period and an example with synthetic identifiers. Have an engineer confirm the moment at which the identifier is persisted and what the lookup can prove. If the lookup is eventually consistent, its delay and interpretation affect the recovery instructions.

The page should also make the end condition clear. “Request sent again” is an action, not a verified resolution. An operator needs evidence that the intended export exists, that it belongs to the original request, and that the recovery did not leave duplicate work requiring cleanup.

Give support evidence without exposing internals

RFC 9457 cautions that problem details are not an implementation-debugging channel and that exposing internals can create security risks. That boundary matters when a documentation example is copied into production. RFC 9457

Our recommendation is to define a small support evidence bundle for each important error class. Include the operation, approximate time with timezone, API version, SDK version where relevant, request or operation identifier if available, and the observed status or connection failure. State which details the customer can safely share and which belong only in protected server logs.

A complete raw request is rarely a good default support instruction. It can contain credentials, personal information or other confidential content. Prefer a redacted minimal reproduction and explicit field names. If a request identifier exists only in a response header, explain that it may be unavailable when no response arrived. Do not make an impossible identifier a prerequisite for asking for help.

Keep the three audiences separate:

  • The application user needs a clear explanation and an available next step.
  • The integrating developer needs stable diagnostic information and recovery guidance.
  • The service operator may need protected implementation traces to investigate.

A page can serve all three without presenting internal exception text as the customer-facing answer. For example, the developer guide can explain how to record a correlation value while the product UI offers a plain-language message and support route.

Review linked diagnostics as carefully as response bodies. If a per-occurrence link reveals account information, its access controls should match that information. A URL in an error is not automatically safe to publish in a public issue. The documentation should say whether a link is shareable, authenticated, or intended only for a particular account.

The useful measure is whether support can investigate with enough evidence while the requester receives no information they are not entitled to see. More verbose error bodies are not automatically better diagnostics.

Test the decisions the error docs teach

The proposed matrix below tests documentation behavior, not provider reliability. We have not executed these exercises. Use synthetic fixtures and an isolated environment, and adapt the expected outcomes to the actual service contract.

ScenarioWhat to inspectDocumentation acceptance question
Two different causes share a statusStable reason and linked handling stepsCan the reader choose the correct action for each cause?
Explanation text changesClient branching behaviorDoes handling avoid dependence on prose?
An unfamiliar reason appearsFallback behavior and preserved evidenceDoes the client fail safely without an endless retry loop?
A create request loses its responseCorrelation and operation lookupCan the reader resolve uncertainty before another creation attempt?
Retry timing is suppliedHeader interpretation and clock assumptionsDoes the example handle the documented format and stopping rule?
Retry protection has expiredLate recovery behaviorDoes the guide avoid implying that an old identifier protects forever?
Access to a private resource is absentResponse and diagnostic outputDoes troubleshooting preserve the intended privacy boundary?
A support reproduction is preparedRedaction and minimum evidenceCan support investigate without collecting unnecessary secrets?

Keep the expected result beside the fixture. A test that merely checks for a 400 or 500 response proves little about whether the published remedy is correct. The assertion should include the next action, its preconditions and the outcome it is supposed to establish.

For a documentation sample, test both the normal error body and a response that is not in the expected format. An intermediary, network failure or unavailable dependency may prevent the caller from receiving the structured explanation the sample expects. The guide should explain the fallback without claiming that every failure contains a parseable problem object.

Have someone unfamiliar with the implementation follow the page using the prepared evidence. Record where they need to ask an engineer what a field means, whether a retry is safe, or which identifier to retain. Those questions identify missing instructions more directly than a spelling or link check.

The exercise can also reveal an API-design gap. If there is no supported way to investigate an uncertain creation attempt, rewriting the error message may not solve the problem. Record the limitation honestly and assign the implementation work separately. Passing a documentation build should never be represented as evidence that these recovery paths were exercised.

Maintain the recovery contract, not just the list of codes

Our proposed maintenance unit is the full recovery instruction: observable condition, supported action, safety conditions, verification and escalation. When one element changes, review the others. A new retry policy or SDK default can make an old example misleading even if the response schema remains unchanged.

For each important error page, keep an internal owner and an evidence date. Review changes to authentication rules, operation lookup, retention, versioning and client retry configuration. Track the examples against the implementation version they describe. Where several API versions have different behavior, make the scope visible before the reader reaches the code sample.

Prioritize by consequence and reader friction. An uncommon ambiguous creation failure may deserve more explanation than a common missing-field error because the wrong response can repeat work. A useful editorial review asks which misunderstanding is most costly, rather than trying to give every status code the same amount of text.

There is no reason to force every API into the same error format for the sake of a documentation refresh. Preserve compatibility where it matters and improve the instructions around the contract already in use. If a representation change is justified, plan its effect on callers separately from the prose revision.

Measure improvement cautiously. Support volume alone does not establish that readers recovered successfully; it can also change with usage or abandonment. In a controlled usability exercise, record whether the participant chose the supported action, avoided an unsafe retry and verified the intended result. Report the task and sample size if those observations are later published.

The question an error page should answer is practical: given this evidence, what can I safely do now? A definition, a machine-readable reason and a troubleshooting link all contribute. The page becomes useful when they lead to a documented decision and an observable result.

Limitations

This is a documentation synthesis, not a measured comparison of API reliability or support outcomes. Seven sources were selected for useful contrasts; they do not represent all APIs or every endpoint. Provider policies were checked on November 16, 2026 and may change. Stripe response-replay and retention claims are scoped to API v1. HTTP status numbers are identifiers, not statistics, and the 24-hour figure is a documented minimum retention threshold, not an observed duration or an exact deletion time. The advanced Stripe guide separately limits retries of an unresolved operation to the first 24 hours. The hypothetical export card and acceptance matrix require implementation-specific verification. No customer data, live payment operations or failure injections were used.

Sources

  1. RFC 9457: Problem Details for HTTP APIsIETF · Accessed 2026-11-16
  2. RFC 9110: HTTP SemanticsIETF · Accessed 2026-11-16
  3. Troubleshooting the REST APIGitHub · Accessed 2026-11-16
  4. Resolve errorsGoogle · Accessed 2026-11-16
  5. Microsoft Graph error responses and resource typesMicrosoft · Accessed 2026-11-16
  6. Advanced error handlingStripe · Accessed 2026-11-16
  7. Idempotent requestsStripe · Accessed 2026-11-16