An API returned HTTP 200—but did the operation actually succeed?

Scope

Use this guide for APIs that create durable domain effects: provisioning, payment, deployment, messaging, account changes, data updates, or workflow starts. It is especially important when an agent calls the API, because a model may equate a successful tool response with a completed objective.

Why it happens

Several events are compressed into “success.” The server may parse and authorize a request, enqueue work, commit one database row, publish an event, update a downstream provider, refresh a read model, and finally produce a user-visible effect. HTTP describes one exchange in that chain.

A connection can also fail after the server commits but before the caller receives the response. The caller sees an error and retries, while the business effect already exists. Conversely, a 200 response can contain a domain-level rejection or report acceptance before later processing fails.

Diagnosis

Choose one operation and draw its state transitions. Name the system of record for each transition and the evidence a caller can observe. Then inject failures:

1. after authorization but before commit;
2. after commit but before response;
3. after queueing but before a worker runs;
4. after a downstream effect but before local confirmation;
5. during compensation.

Check whether the client can distinguish retryable failure, permanent failure, success, and unknown outcome. If its only evidence is a status code or model-generated sentence, the contract is incomplete.

Solution

Give every operation a caller-supplied idempotency key or stable request ID with defined scope and lifetime. Return an operation resource that exposes current state, accepted parameters or digest, timestamps, target, and failure or compensation details.

Define a terminal business condition independently of transport. For a deployment, it may include the desired version observed healthy in the target environment. For a message, it may mean accepted by the provider, not read by the recipient; label that boundary honestly.

When the outcome is unknown, reconcile by operation ID and authoritative target state before retrying. Instrument the transitions so evaluation can grade actual effects rather than tool-response text.

Artifact

Adapt this state model:

State	Meaning	Authoritative evidence	Allowed next step
received	Request parsed and identified	Request ledger	Authorize/reject
authorized	Current policy permits proposal	Decision record	Validate preconditions
accepted	Work admitted but incomplete	Operation resource	Poll/subscribe/cancel
committed	System-of-record mutation completed	Commit/effect record	Verify downstream state
visible	Intended read model reflects effect	Versioned authoritative read	Confirm outcome
confirmed	Domain success condition met	Outcome verifier	Close
failed	Terminal failure with no intended effect	Failure record	Repair/new request
compensated	Prior effect reversed within stated boundary	Compensation record	Review residual effects
unknown	Evidence cannot distinguish states	Gap record	Reconcile; do not blind retry

Common mistakes

• Mapping every 2xx response to completed.
• Returning no stable operation identifier for asynchronous work.
• Retrying after a timeout without checking for an existing effect.
• Reading from a cache and treating it as authoritative confirmation.
• Claiming rollback when compensation leaves external or user-visible residue.