HTTP 202 needs a completion contract

HTTP 202 has been easy to misread for a long time. RFC 9110, published in June 2022, defines it as acceptance for processing, with processing unfinished. The server might never perform the requested operation.

An agent tool that turns this into “done” has crossed a boundary the protocol deliberately leaves open. HTTP 202 needs a completion contract: a stable operation identity, observable progress and a terminal outcome that the caller can verify. A successful submission is useful. It is only the first receipt.

HTTP 202 leaves the outcome open

The HTTP specification describes 202 as noncommittal. A response should explain the current status and point towards a status monitor. It does not promise that a later HTTP response will arrive automatically with the final outcome.

Microsoft's asynchronous request-reply pattern offers a concrete application design around that gap: accept work, expose a status endpoint and let the caller inspect the operation. Its polling guidance is a design pattern, not an extra guarantee supplied by the number 202.

The practical mistake happens when a tool wrapper compresses that sequence into one boolean. The API answered “I accepted your request.” The model receives “success.” The final user-facing sentence becomes “your report is ready,” even though no report has been produced.

Keep acceptance separate from completion

I would give an asynchronous tool a result vocabulary that distinguishes accepted, running, completed, failed and unknown. Those are application states, not a claim that every API must use these exact names.

Unknown deserves its own place. A lost connection after submission may leave the client unable to tell whether the server accepted anything. Calling that failed encourages a duplicate submission; calling it completed encourages a false promise. The next action should be reconciliation against the operation identifier or documented idempotency contract.

Completion also needs an object. For a generated report, it might be an accessible artifact with the expected format. For a data export, it might be a manifest and a retrievable file. The status endpoint saying completed is one observation; the promised deliverable being usable is another.

An export needs a retrievable result

Imagine a finance assistant asked to prepare an export. I would let it tell the user that the export request was accepted and retain the operation ID. Its next step would inspect that operation, within a bounded waiting budget, rather than submit the export again.

If the operation remains active when that budget ends, the assistant should retain enough state to resume. A local waiting deadline should not silently rewrite the remote operation as cancelled. Cancellation needs its own supported action and confirmation.

Before reporting delivery, I would check that the returned artifact belongs to the requested export and is accessible in the intended account. This is a proposed workflow, not a claim about a client deployment or a measured reduction in errors.

The same separation should appear in telemetry. Submission latency, processing latency and artifact availability answer different questions. Combining them into a single success rate makes a fast intake queue look like a reliable service even when downstream work is stuck.

A synchronous endpoint may already return the finished resource. In that case, adding a polling layer buys needless complexity. Apply this contract where the operation genuinely outlives the request.

What's in it for you

• Test an accepted job that later fails and one whose outcome is temporarily unknown.
• Make the assistant's final claim depend on the promised artifact, not the submission response.

A 202 response starts an obligation; your tool must define what evidence closes it.