Error Codes

When an agent executes a paid request through a spending session, the backend enforces the session's budget and scope constraints. If a request violates these constraints, the payment is refused with one of the error codes below. The agent reads the error code from the response and takes the appropriate recovery action.

Session Spending Errors

session_rule_exceeded

What it means: A single transaction exceeds the session's max_amount_per_tx limit.

What the agent does: The agent cannot proceed with this transaction. It must either:

• Request a new session with a higher per-transaction limit, or
• Break the request into smaller chunks that each fit within the per-transaction cap (if the service supports batching).

The agent does not retry the same request against the same session.

session_total_exceeded

What it means: The cumulative spending across all transactions in this session exceeds the session's max_total_amount budget.

What the agent does: The session's budget is exhausted. The agent must request a new session with sufficient budget to complete the remaining work. The agent does not retry the same request against the same session.

session_endpoint_forbidden

What it means: The agent attempted to access an endpoint outside the session's scope constraints. The session was created with execution_constraints that restrict which endpoints the agent can call (e.g., only /api/weather or only example.com), and this request fell outside that scope.

What the agent does: The agent cannot proceed with this endpoint. It must either:

• Request a new session with broader scope constraints that include the target endpoint, or
• Use a different endpoint that falls within the current session's scope.

The agent does not retry the same request against the same session.

Other Session Errors

Additional error codes returned during session creation or execution include:

• session_asset_forbidden — The settlement asset is not allowed by the session policy.
• session_forbidden — General session policy violation.
• session_owner_forbidden — The session owner does not match the executing agent.
• payment_target_forbidden — The payment target (merchant) is not allowed.
• payment_redirect_not_allowed — The payment was redirected to a disallowed target.
• session_request_forbidden — The session request was rejected by the backend.

For all of these, the agent inspects the hint field in the error response for recovery guidance and creates a new session with corrected parameters.