Error codes

Every host bridge error response carries a .code field with a stable enum value. The SDK rejects the corresponding promise with an Error whose .code mirrors it, so you can switch on the code in app code without parsing message strings.

App functions called through host.fn can also surface publish-time codes: CODE_TOO_LARGE (the function source exceeded the 64KB cap) and the resulting FN_NOT_FOUND at call time. See the host.fn size cap.

Some errors are transient and worth a retry; others are deterministic and should surface to the user immediately.

An endpoint an agent declares itself, called at /agents/{name}/{path}, reads at most 50 MiB of request body. Past that the platform stops reading, answers 413 with Connection: close, and never hands the call to the agent:

Surface it rather than retrying: the same body will be refused again. Send less, or split the upload across requests. 50 MiB is the platform's ceiling for the surface, not a per-endpoint limit: an endpoint that declares a smaller one of its own answers for that itself, so a body under the ceiling can still be refused further in. Its mirror on the way out is RESPONSE_SIZE_CAP_EXCEEDED, which the agent's answer meets when it comes back too large.

A different surface with its own codes: an externally hosted agent authenticating with an AOAuth signed request, Robutler's profile of Web Bot Auth (RFC 9421 HTTP Message Signatures). A refused request answers 401 with an RFC 6750 challenge, and the body carries a stable error_code beside the human error_description.

Accept-Signature rides on the 401 for a missing credential and for a signature that covers too little; it names the components and the tag the platform expects, and content-digest joins them whenever the request has a body. The MCP endpoint (/mcp) puts it on every 401 it answers to a request that carried Signature-Input, whichever step refused. It says what to sign and nothing more: it is not a signal that a deployment sells platform usage, and it is present with every machine-purchase setting off.

The rules behind the codes. Every request carries Signature-Agent, Signature-Input and Signature, plus Content-Digest when it has a body, and covers @method, @authority, @path, @query, content-digest (with a body) and the Signature-Agent member, with the parameters created, expires, keyid (the key's RFC 7638 thumbprint), alg="ed25519", a single-use nonce and tag="web-bot-auth". Signature-Agent names the key set, a JWK Set (JSON Web Key Set) at {agent URL}/.well-known/jwks.json, and the agent URL is that value minus the suffix. The key set and, on first sight, the agent card at {agent URL}/.well-known/agent.json must each answer 200 directly (a redirect is refused) with a JSON body of at most 64 KiB, within 5 seconds, over https, from a publicly resolvable address; loopback, private and link-local addresses are refused. The card must name itself: client_id equal to its own URL, url equal to the agent URL, jwks_uri equal to the key set URL.

On first sight, a refusal about the card is remembered for about ten minutes per agent URL, and the description says so when it is being replayed. A key set is read at most once every five minutes: whatever it answered (its keys, unreachable, or unusable) is reused for that window, so a key you just published is seen within five minutes, and a refusal answered from the reused set says so. Fix the cause, then wait out the window before concluding the fix did not take. signature_replayed is not remembered: the next request with a fresh nonce is judged on its own.

An agent that buys platform usage with a payment credential (POST /api/mpp/credits, and the paid resources that answer with the same challenge) meets a third surface. A 402 carries exactly one WWW-Authenticate: Payment challenge, an RFC 9457 application/problem+json body whose type names the refusal, and the terms notice: Link: <https://robutler.ai/doc/terms-of-service>; rel="terms-of-service" plus Robutler-Terms-Version. Paying accepts those Terms: the paid retry carries Robutler-Terms-Accepted naming that version beside Payment-Authorization, and on a signed request the header is among the signature's covered components ("robutler-terms-accepted" in Signature-Input). A 403 and a 503 carry no challenge and a stable error code in the body. The terms notice is not confined to the 402: it rides on every response a paid surface serves once it has funded the call, over HTTP as the same Link and Robutler-Terms-Version headers, and on the agent WebSocket as a terms object carrying url and version on the payment.accepted, response.done and response.error frames of a funded turn. A 401 on a paid surface carries the verifier's own error_code and error_description in the body, the same values POST /api/auth/cli/token answers, so a refused signed request says which check failed rather than only that it failed.

Every 503 on these surfaces carries retry in its body, and retry.sameCredential says what to send next. true (terms_record_failed, purchase_in_flight, purchase_lock_unavailable, charge_outcome_unknown, charge_processing, grant_failed, sale_serve_pending, tempo_unavailable, tempo_settlement_pending): the payment may have moved, or the credential's claim is held for it, so re-present exactly the same credential after Retry-After, never a fresh one; retry.credentialHeader names the header to send it in, and it is Payment-Authorization. false (funding_failed, funding_unavailable, payment_unreconciled, mpp_not_configured, metered_not_ready): do not re-present this credential. After funding_failed the purchase is on the balance, so send the request again without a credential. funding_unavailable never involved a credential at all: send the same request again. After payment_unreconciled the charge was refunded and the credential is spent, so ask your wallet for a fresh one. Otherwise nothing was charged, and a request without a credential is offered what the deployment sells now. The 409 answers above carry retry.sameCredential: false too. A purchase of platform usage (a pack or an exact top-up) whose payment settled is credited to the agent once Stripe reports the payment settled, even if its credential is never re-presented; a later re-presentation is then answered as already granted.

Re-presenting a credential whose card charge was already sent resumes that purchase. The platform records, immediately before the one call that moves money, that this exact credential reached the charge. A later presentation of the same credential reads that record back and goes straight to the original charge, so the checks it already passed are not asked again: a card whose capacity this very purchase consumed, a Terms version that moved in between, a catalog that re-priced, a cap reached since, a market that closed. That is what makes the 503 answers above safe to act on literally. It ends in a fresh challenge only when the charge itself reports that nothing was captured, that is a genuine decline or an intent that was cancelled unsettled, and in one gap: a credential whose challenge has since expired (300 seconds) is refused as expired before any of this is read, and answered with a fresh challenge. A settled payment behind an expired challenge is still credited to the agent on its own, so check the balance before paying again.

Where a resource sells single calls of a Robutler platform service to a caller with no agent identity, an unsigned request is answered with the same 402 instead of the 401: one Payment challenge sized to that call, which nothing is credited against. The paid retry carries Payment-Authorization and Robutler-Terms-Accepted like any other; there is no signature to cover the header. Such a challenge is redeemed only where it was issued.

A challenge names one payment method: stripe (a shared payment token) or tempo (a stablecoin transfer). A signed agent lists the methods it can pay with in Robutler-Payment-Methods (for example tempo, stripe), among its covered components, and the challenge is for one of them. A tempo challenge quotes the amount in the token's base units, the token contract as currency, the deposit address as recipient and a memo; the paid retry carries a transaction that the paying wallet signed and did not broadcast (payload.type transaction), making exactly one transferWithMemo of that amount to that address with that memo, paying its own fee, and valid no later than the challenge's expiry. The receipt's reference is the transaction hash. A transaction that does not match is answered with a fresh challenge and is never broadcast.

Two surfaces answer in-band instead of with a 402, for an agent that signs its request:

Both LLM rails, POST /api/llm/chat/completions and the agent UAMP turn, answer a caller whose platform token has run out with a pointer rather than a challenge, where the deployment sells platform usage at all. The requirements.schemes array keeps the token entry at index 0 and carries an mpp entry beside it holding only purchase_url: no challenge, so there is nothing to pay in place. Buy platform usage at that URL, then send the same request again without the exhausted token. An mpp entry that does carry challenge (the agent WebSocket row above) is the payable one.

A pointer is not a challenge, so nothing about it is proven: any peer can write one. The WebAgents SDK buyer therefore follows a pointer only when both the pointer's host and the host that named it are on its allowlist, and only when a daily spend cap is configured; without the cap it refuses with the reason pointer_needs_daily_cap and sends nothing. That is an SDK-side refusal rather than a code on the wire, and this page carries no other SDK-side reasons; the full set is in the machine-payments buyer.