Agent-Readable APIs Need Reviewer-Readable Recovery Paths

Executive summary

Agent-readable and reviewer-readable are different requirements, but they do not need different systems.

A good API contract can support machines with structured operations, parameters, errors, callbacks and idempotency references while also supporting reviewers with versions, correlation IDs, timestamps, source-native states and explicit recovery preconditions.

The key is to avoid compressing several different facts into one success flag.

For a recovery review, keep at least four layers separate:

1. transport and HTTP;
2. the tool or protocol envelope;
3. provider payment or business state;
4. settlement and reconciliation evidence.

Then add a fifth dimension that belongs to the reviewer rather than the provider: what is known, unknown or conflicting?

That last category matters. “Unknown” can be the correct result when evidence does not justify either success or failure.

Callable is not the same as reconstructable

OpenAPI is a useful starting point because it can describe a unique operation, parameters, request bodies, expected responses and out-of-band callbacks. The current OpenAPI Specification is 3.2.1, published on September 10, 2026.

That structure helps an agent know how to call a service. It can also help a reviewer identify which operation was intended and which inputs were valid for that operation.

But a schema is not the whole recovery contract.

OpenAPI itself notes that a response description is not necessarily expected to enumerate every possible HTTP status. And even a perfectly documented HTTP response does not automatically tell a finance reviewer whether a payment was economically completed or reconciled.

So the recovery record should preserve the actual provider/API/schema/SDK or tool-adapter version that was used, not just “OpenAPI compliant.” It should also preserve environment and account scope, operation identity, normalized non-sensitive arguments, and the source that defines documented side effects.

A tool returning successfully can mean the tool call completed. It does not necessarily mean the payment did.

Four layers of state

The fastest way to create a bad recovery process is to let one status carry several meanings.

Consider four layers.

Transport / HTTP. Did the request leave the client? Did a response arrive? What status was observed?

Tool / protocol envelope. Did the adapter finish? Did it return a local error, a provider response, or an intermediate proof object?

Payment / business state. What provider-native object and state exist, if any?

Settlement / reconciliation. What downstream record supports closure for the finance question?

HTTP 202 is a good illustration of the boundary. RFC 9110 says 202 Accepted means processing was accepted but has not completed; the request might or might not eventually be acted upon. That is useful transport-level information. It is not a settlement statement.

The same discipline applies to richer tool outputs. If a payment tool returns a signed proof or a locally valid envelope, preserve that state exactly. Do not silently rename it “paid” unless the relevant provider or rail defines it that way and later evidence supports the conclusion.

Errors need provenance, not just prose

A reviewer should not have to reverse-engineer a machine policy from an English error message.

Keep separate fields for HTTP status, provider-native machine code, adapter or downstream code, and the human-readable message.

IXOPAY’s current documentation is a useful example. It distinguishes platform errorCode and errorMessage from adapterCode and adapterMessage when a downstream system supplies its own result. Its documented groups include validation, payment, network, post-processing and Status API errors.

That helps because two superficially similar errors can have different recovery implications.

IXOPAY code 3001 is documented as an upstream timeout. 3005 is a communication error. 8001, “Transaction not found,” is specifically scoped to the connector determined by the API key.

That last scope is the important part. A lookup miss in one connector scope is not automatically proof that no payment exists anywhere. A reviewer should preserve the exact lookup key and scope instead of upgrading “not found here” to “never happened.”

The same rule applies to unknown codes: do not guess a normalized state from prose.

When the outcome is indeterminate

Stripe’s current error documentation gives a particularly clear provider-specific example.

For certain server errors, Stripe says to treat the result as indeterminate and warns that the original request may have produced side effects. Its idempotency documentation describes how repeated requests can be associated with the same provider-specific key.

That is a recovery contract. It is not a universal payments rule.

The reviewer’s evidence path can include a provider object lookup, documented idempotency behavior for the exact operation, asynchronous events, provider ledger evidence, and later reconciliation. If those sources still do not establish the outcome, the case remains unresolved.

This is a useful operating discipline because it blocks a dangerous shortcut:

no response → failed → retry

A timeout is an observation gap. Sometimes documentation can narrow the gap. Sometimes later provider evidence closes it. Sometimes it stays open long enough to require a human decision.

Idempotency needs scope

An idempotency reference is valuable, but the word “idempotent” is too often treated as a magic guarantee.

RFC 9110 defines idempotent HTTP methods and warns against automatically retrying a non-idempotent request unless the client has additional knowledge that the request semantics are actually idempotent or knows the original request was never applied.

Payment providers can define stronger request-specific behavior. When they do, preserve the details.

A reviewer should ask:

• Which provider and account scope does the key belong to?
• Which operation and API version?
• Must the repeated payload be identical or equivalent?
• How long is the reference retained?
• What happens after expiry or pruning?
• How are concurrent attempts handled?
• Are failures cached?
• Does a second provider recognize the same reference?

The last question should normally start as “unknown,” not “yes.”

AWS AgentCore’s current ProcessPayment documentation, for example, defines a clientToken for request idempotency and separately identifies payment sessions and payment instruments. That is useful provider-specific structure. It does not prove end-to-end exactly-once behavior across a merchant, blockchain, another payment provider and a finance ledger.

Request ID, payment ID, idempotency key and event ID should remain different fields.

Retries and failover are decision boundaries

A retry can occur in more than one layer: HTTP client, SDK, orchestration layer, provider, or webhook delivery.

If those layers are invisible to the reviewer, two “retries” can multiply into several attempts.

So the recovery record should capture retry history by layer and preserve any documented preconditions, backoff hints, retry budget and deadline.

Most importantly, it should distinguish same intent from changed intent.

Changing the amount, payee, currency, resource or mandate scope is not merely a retry. It is a changed proposal and should normally return to the relevant decision boundary.

Provider failover deserves the same treatment. If provider A has an unknown outcome, sending the same economic intent to provider B can create a second payment unless the first outcome is resolved or a human-authorized exception explicitly accepts that risk.

This is why a reviewer-readable recovery path is not an auto-retry algorithm. It is a way to show when automation should stop pretending it knows enough.

Callbacks are evidence, not magic state

Asynchronous systems introduce another common compression error: treating “webhook received” as “business outcome complete.”

Those are separate facts.

IXOPAY documents callbacks as transaction status updates and requires HTTP 200 with body OK to acknowledge successful receipt. Its guide separately says internal state can be updated after callback authenticity has been verified.

Stripe documents automatic webhook retries, possible duplicate delivery, non-guaranteed event order, and signature verification.

A reviewer therefore wants separate evidence for:

1. receipt;
2. authenticity;
3. deduplication;
4. processing;
5. the provider business state represented by the event.

Event time and observed time also belong in separate fields.

A late callback should be appended to the evidence history. It should not silently overwrite a later authoritative state just because it arrived last.

Recovery is not rollback

Cancellation, void, refund, reversal and reconciliation are often spoken about as if they were one undo button.

They are not.

Each can have different preconditions, authority, identifiers and final states. A compensation request can itself be pending, fail, be reversed, or require separate reconciliation.

For reviewer purposes, compensation should be a child record linked to the original attempt. The original payment history does not disappear when a refund is requested.

The case closes only when the selected closure criterion is supported by evidence. Depending on the workflow, that may require a provider-native terminal state, settlement evidence and a finance reconciliation record.

If those records are missing, “unresolved” is better than a green indicator based on optimism.

Practical template: Download the Recovery Path Evidence Record →

A compact recovery matrix

Full matrix: Download the State / Error / Recovery Matrix →

Negative walkthrough: timeout without closure

A synthetic agent attempts one payment.

The caller records operation version, logical payment ID, attempt ID, amount in minor units, currency, payee reference, account scope and an idempotency reference. The transport times out.

A status lookup in the recorded account returns no object, but the documentation does not establish that this lookup is exhaustive of all downstream processing.

The correct reviewer conclusion is not “failed.”

It is:

Outcome unknown. No new economic attempt is authorized from the current evidence. Continue evidence collection or escalate to the designated human owner.

That conclusion can feel unsatisfying. It is still better than manufacturing certainty.

Positive walkthrough: closure with linked evidence

Now take a second synthetic case.

The original call returns 202. Later, a provider lookup returns a payment object in the provider’s documented terminal state. An authenticated, correlated event points to the same provider object. A reconciliation record then matches the payment to the expected obligation.

The reviewer can close the case under a stated internal closure criterion because the evidence chain is complete for that reader job.

That does not prove universal safety, legal finality or production reliability.

It proves something narrower and useful: this case can be reconstructed from linked evidence without guessing across layers.

Agent-Readable / Reviewer-Readable API Evidence Checklist

For each integration, ask whether the record preserves:

• the actual API/schema/SDK/tool-adapter version and operation;
• environment, tenant/account and units;
• normalized non-sensitive arguments and logical-payment/attempt IDs;
• HTTP, tool, provider and reconciliation states separately;
• native error code, adapter code and human message separately;
• lookup scope and completeness limits;
• idempotency scope, payload equivalence, lifetime and concurrency semantics;
• retry history by layer;
• callback receipt, authenticity, deduplication, event time and observed time;
• compensation child records and authority;
• unresolved contradictions;
• a human disposition and explicit closure criterion.

The checklist is a Treasury Desk author synthesis. It is not an industry standard, implementation, security control or certification.

Full checklist: Download the Agent-Readable / Reviewer-Readable API Evidence Checklist →

What this does not prove

Reviewer readability does not prove API reliability.

A well-documented recovery path does not prove that an implementation always follows its documentation, that a provider is secure, that a payment is legally authorized, that a transaction is fraud-free, or that a system is production-ready.

The absence of a public field also does not prove the absence of an internal control.

This method does not turn Treasury Desk into a payment executor, recovery service, SDK, control plane or compliance system. Treasury Desk remains a read-only analytics, monitoring, reporting and decision-support product. The contribution here is a reviewer-facing method for structuring public and operational evidence.

Method and sources

This article reviewed the current OpenAPI 3.2.1 specification; RFC 9110 and RFC 9457; current Stripe error, idempotency and webhook documentation; current IXOPAY callback, Status API and error-code documentation; and current AWS AgentCore payment documentation. The AWS/t54 article was used only as implementation/source-discovery context and not as independent assurance.

The reviewer templates and normalized certainty states are author synthesis. Provider-native terminology is preserved where it matters.

Treasury Desk methodology: https://treasurydesk.io/methodology/
Treasury Desk product boundary: https://treasurydesk.io/legal-scope/

If you work on payment APIs, the useful question is not “Do you retry?” It is: what evidence would let a second reviewer decide whether retrying is still the same intent — and whether another attempt is authorized at all?