An API contract must explain the customer outcome

A customer requests a document export. The API returns HTTP 202, and the interface displays “Your file is ready.” The customer clicks Download and receives nothing because conversion is still running.

The endpoint behaved as designed. The consumer's interpretation did not. API contract design has to explain the business result a client may show, as well as the shape of a successful HTTP response.

Define the promise at each state

RFC 9110, section 15.3.3, defines 202 as acceptance for processing without completed processing. The response should describe the current status and point to, or include, a status monitor. Acceptance therefore cannot carry the same product promise as an available export.

For this fictional document service, the contract could expose an operation reference and a status resource. The following states are a proposed application design, not a required HTTP vocabulary.

An HTTP 200 response from the status endpoint means the status query succeeded. It does not transform an application state of processing into completed.

Give the consumer enough evidence to behave correctly

The consumer needs to know which operation the response describes, which state values it must handle and which actions are allowed. The result link needs its own access and expiry rules. A link existing in a payload does not prove that every caller may retrieve the file.

The contract should also define what happens when the client cannot determine the current state. Preserve the operation reference and show that the result is being checked. Do not invent completion or immediately create another job because the last status request failed. The design of uncertain interface states is covered in the UI state inventory.

Make errors useful without making prose an API

RFC 9457 provides a structure for problem details. Its type identifies the kind of problem; detail explains the particular occurrence to a person. Clients should not parse that explanatory prose to make decisions. The specification also cautions against exposing sensitive implementation details.

For the export, a stable problem type might distinguish unsupported input from an unavailable result. The exact identifiers and remediation rules belong in the service's contract. Keep internal storage paths or stack traces out of the customer-facing response.

A translated explanation can change wording while preserving the machine-facing meaning. Conversely, keeping the same wording while changing whether an operation can continue is a contract change that needs review.

Test the consuming product, not just the response schema

Ask the client team to demonstrate accepted, delayed, completed, failed and expired operations with controlled fixtures. Include an unfamiliar optional response field and an unknown state value. Define the supported compatibility policy in advance: a client that cannot interpret a state should retain uncertainty and use an approved escalation path, rather than display success.

Check the response and the actual interface together. Does the Download action appear only when the result is usable? Does the customer keep the same operation reference through a lost status response? Can support find that operation without asking the customer to repeat the request?

Record these examples in the development handoff. A schema that validates all five payloads is useful evidence, but the customer promise is only tested when the consumer uses each one correctly.