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.

An approved email goes out only after Pepper records it. An approved refund, payment check or AI connection test starts only after Pepper records that it started. If an execute call fails after that, retry with the same execute key: Pepper continues the same request and never sends the email or the refund twice. While the request is still running, a retry returns approval_running. You cannot cancel a request that has started.

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, and error.messages with the reasons for each field. A reason never repeats the value you sent. A refusal that Pepper explains in words on the screen also has error.message with the same sentence, for example "Publish what this widget shows first, such as its form, then publish the widget." Responses exclude internal error details and credentials.

A stale version returns 409 conflict with current_version where the record has one, such as a draft, a deal, a task or a card. Read the record again, compare it with your change and send a new key. A rate limit returns 429 with the Retry-After header and retry_after in seconds.

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 (`current_version`) or correct a reused key
409	`approval_required`	The change needs the delegated person's approval. Use its prepare tool from Approve sensitive steps, or link an existing record
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_policy_stopped`	Automatic consent no longer applies. Read the current request and obtain a new decision; do not retry execution blindly
409	`approval_stale`	The record, its recipients or the connection changed. Read the record and prepare a new request
409	`approval_used`	Retry with the original execute key to retrieve the result
409	`approval_running`	The approved change has started. Retry with the same execute key after a short wait; do not cancel it
409	`approval_cancelled`	The connection cancelled this request. Prepare a new request if you still need the change
409	`approval_executed`	The request already ran, so it cannot be cancelled. Read it with `approvals_get`
410	`approval_expired`	Prepare a new request and obtain a new decision
413	`payload_too_large`	Reduce the encoded request body to its transport limit; only named tools have larger limits
415	`json_required`	Send the JSON content type
422	`validation_failed`	Correct the named fields with the reasons in `messages`; use a new key for changed input. An argument that is not part of the tool is refused. A cursor from another query is refused here: start the list again
429	`rate_limited`	Wait for `Retry-After` seconds; 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, approval results and audit evidence remain. Revocation cannot erase a client's saved copies.

Pepper keeps the request receipts and the refresh tokens of a connection while you can use it. Thirty days after the connection ends, a daily task removes its receipts, its tokens and its approvals that were not executed. An executed approval stays with the invoice it issued. Expired sign-in codes and access tokens go one day after they expire.

Read connection setup and privacy boundaries.