Limits and errors

Lifetimes, rate-limit keying, every error code.

const result = await payman.forUser(userId).run(text);

if (result.kind === "error") {
  show(result.guidance);                            // written for humans
  if (result.retryable) retryLater(result.retryAfterMs ?? 1000);
}

Money-task wire failures come back as the error result kind; run() never throws for them. On the blocking route the SDK retries a retryable failure once before resolving; streamed turns resolve without a retry. Schedule any second attempt for later and honour retryAfterMs when it is set.

Structured data methods throw FinancialDataError instead. Their job limits, resumable timeouts, and partial-result behavior are covered in the financial-data guide.

Lifetimes

What	Lifetime	On expiry
Connection (the grant)	90 days	run() returns needs_connection; offer the button again
Connection, unused	30 days idle	Revoked automatically. Same path: offer the button again
App registration	90 days	Renew it from the developer console; existing connections resume
Authorization code	60 seconds, single use	It burns on a failed exchange too; start the flow again
Approval	About 15 minutes, stamped on the approval as expiresAt	The state becomes expired; run the turn again

status() reports health: "expiring_soon" from 14 days out on either 90-day clock.

A connection nobody uses is swept after 30 days, whether or not the 90-day clock has run. Any call resets it, so an app a customer actually uses never hits it. One a customer connected and forgot does.

Rate limits

The budgets are deploy configuration, so no figures here. The keying is the contract:

Traffic	Keyed on
Turns and their follow-ups (interact, stream, user actions, approval polls)	The grant
Credential minting (register, rotate, renew)	The user
The token exchange and the app self-read	The app
The public consent read, and everything unauthenticated	IP

Per grant is the one to pace: each customer budgets separately, so the traffic that hits it is yours, and one customer can never starve another. A 429 surfaces as rate_limited.

Error codes

result.code is a closed set.

Code	Retryable	Meaning
invalid_request	No	Malformed call. Your bug.
needs_connection	No	Never actually surfaces as an error: a 401 becomes the needs_connection result kind instead.
connect_grant_race	No	The customer reconnected in another tab, replacing this grant. Offer consent again.
deployment_paused	No	Paused from the customer’s Payman console. Only they can resume it.
deployment_incomplete	No	The customer’s Payman setup is unfinished. Not fixable from your app.
insufficient_scope	No	The grant does not cover the operation.
agent_failed	No	The customer’s own agent answered, and the answer was that it could not do it.
agent_timeout	Yes	The customer’s own agent took too long.
agent_unreachable	Yes	The customer’s own agent could not be reached.
agent_busy	Yes	The customer’s own agent is still working on their previous request. Nothing ran and nothing was charged; the same call succeeds once that run finishes.
rate_limited	Yes	Too many requests. retryAfterMs says how long to wait.
server_error	Yes	Payman had a problem.
stream_error	Yes	The stream ended without a result. The turn failed; nothing was delivered.
transport_error	Yes	Could not reach Payman at all. Check connectivity and PAYMAN_BASE_URL.

deployment_paused and deployment_incomplete never succeed on retry. Alert yourself rather than asking the customer to fix them mid-conversation.

agent_busy is the one retryable code that is not a failure. A customer’s agent runs one turn at a time per conversation, so a turn sent while the previous one is still running is turned away rather than queued. Send the same call again after a moment; do not tell the customer something broke.

The hosted MCP server has a twin of it, run_in_progress, which means exactly the same thing about a run it is already holding. Neither charges anything and neither ran.

Two more statuses are not errors at all and never reach this table: needs_provider and no_capable_provider arrive as ok results. See the Wallet.

The served contract

HTTP statuses and wire result names live in the HTTP API. The spec itself is served on the API origin and parity-tested against the router on every build, so a route it does not describe does not exist:

curl -s https://paygent-cloud-server-production.up.railway.app/openapi/paygent-cloud-api.yaml

The tool definition is served the same way, versioned by date:

curl -s https://paygent-cloud-server-production.up.railway.app/connect/tool-definition | jq .version