Decisions and errors

Status: Draft 0.4, pre-release. Sources: Draft 0.4 sections 8 and 13, binding section 6, registries/reason-codes.json and schemas/error.schema.json.

Every call an agent makes is either decided or rejected as malformed.

• A decision is the enforcement point applying the seller's grant and terms: auto, ask or forbid. It always carries an RCTP-Decision header. A forbid always names exactly one registered reason, so your agent can act on it without a human reading a message [13].
• A protocol error means the request itself was wrong: bad JSON, an unknown route, an unsupported version, a reused Idempotency-Key. It carries no RCTP-Decision header.

#The RCTP-Decision header

The header is an RFC 9651 Structured Field Item: a Token (auto, ask or forbid) with parameters [8.2] (binding 6). The reference gateway serialises it without optional spaces:

HTTP/1.1 202 Accepted
RCTP-Decision: ask;approval_id="apr_01K8ZB7";expires_in=900;on_timeout=deny

HTTP/1.1 403 Forbidden
RCTP-Decision: forbid;action="offer.accept";reason=below_floor

HTTP/1.1 429 Too Many Requests
RCTP-Decision: forbid;reason=offer_budget_exhausted;retry_after=3600

Parse the header with a library (parseDecision in @rctp/sdk, parse_decision in rctp, structured-headers, dunglas/httpsfv, http-sf), never with string matching.

A refusal body validates against the Refusal branch of error.schema.json:

{ "reason": "below_floor", "action": "offer.accept" }

It may also carry retry_after, approval_id, offer_id and a short message. It never carries a floor: a schema test fails if any schema other than listing-terms and terms-submission has a floor field.

#The check order

The enforcement point runs its checks in a fixed order and stops at the first refusal [8.1] (binding 6).

Why this order:

• The cheapest refusals come first.
• The floor check comes after the counterparty check, so a buyer who fails the requirements never learns how close their offer was.
• The floor check comes before the tier, so an accept below the floor is refused even when offer.accept is auto (V1, INV-1).
• Once a buyer agent's budget (or its operator's ceiling) for a listing is spent, every offer from it on that listing gets 429, even one above the floor. Otherwise 200-versus-429 would reveal the floor [8.5].

A buyer offer (offer.create) has no tier: one that passes is delivered with 201. On a listing without approved terms there is no seller agent, and the offer goes to the marketplace as an ordinary offer (auto) [6.5]. The fixed forbids, deal.sign_contract and account.update, are always 403 action_forbidden once the signature is valid (INV-3).

Every decision, including every refusal, is written as an entry in the deal record [10.1].

#Reason codes

All 22 codes from registries/reason-codes.json, in the order of Draft 0.4 section 13. "v0.2" says whether the reference gateway at v0.2.0-draft.4 can return it.

#Protocol errors

Protocol errors are not decisions. They carry no RCTP-Decision header and use the ProtocolError branch of error.schema.json:

{ "error": "invalid_request", "message": "…" }

#In the SDKs

ForbidOutcome.reason is typed as the registered Reason union. REASON_CODES and REASON_HTTP_STATUS are generated from the registry by pnpm codegen. The Python SDK returns Auto | Ask | Forbid with the same reasons.

#On other transports

Draft 0.4 carries the same decision on every transport [12]. v0.2 ships the REST binding only; the MCP and A2A bindings are not built yet.

Source: docs/decisions-and-errors.md