Errors, retries and revocation

For: developers connecting an HTTP or MCP client. Start with Agent API and AI clients.

AI is optional. You confirm invoice issuance in Pepper.

Idempotency and conflicts

Each write needs an idempotency key of 1–80 ASCII letters, digits, underscores or hyphens. An identical retry returns its original response.

Keep the JSON values and field order identical. Reusing a key with another payload or target returns 409.

A receipt describes the original write. Read the document for its current status and version. A stale update changes nothing.

Keep your input after a conflict. Read the latest version, review the differences and use a new key. Failed draft transactions store no success receipt.

Executed approvals retain a separate result. A new execute key on the same approval returns approval_used.

Revocation and current permission checks still apply to retries. A retained receipt does not restore lost access.

Errors

HTTP tool errors contain error.code. Validation returns error.fields, a list of field paths. Responses exclude exception messages and credentials.

Status	Code	Recovery
401	`unauthenticated`	Check expiry, revocation, the delegated user and application URL
403	`forbidden`	Check HTTPS, host/port, Origin, grants, current permissions and demo mode
404	`not_found`	Access is off, or the route/record is missing or outside scope
409	`conflict`	Read the latest version or correct a reused key
409	`approval_pending`	Wait for the delegated person's decision
409	`approval_rejected`	Respect the decision; review the draft before any new request
409	`approval_stale`	Read the draft and prepare a new request
409	`approval_used`	Retry with the original execute key to retrieve the result
410	`approval_expired`	Prepare a new request and obtain a new decision
413	`payload_too_large`	Send a tool body of 256 KiB or less
415	`json_required`	Send the JSON content type
422	`validation_failed`	Correct the named fields; use a new key for changed input
429	`rate_limited`	Wait for the minute window to clear; reduce request frequency
503	`unavailable`	Keep the input; retry with the same key if the earlier write may have succeeded

A hidden record and a missing record produce the same 404. Another connection's approval or an incorrect nonce also returns 404.

After an execution conflict, read the approval and document. Do not assume the client issued anything from a prepared or approved state.

Revocation and retained evidence

Revoking a connection stops its future calls. Turning agent access off revokes all connections. Turning browser sign-in off revokes browser connections.

Expiry, user deactivation, session-revoking permission changes, owner transfer or a changed application URL can also stop access.

Saved drafts, issued originals, connection metadata, request receipts, approval results and audit evidence remain. Revocation cannot erase a client's saved copies.

Read connection setup and privacy boundaries.