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);
}

Every wire failure comes 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.

Lifetimes

What	Lifetime	On expiry
Connection (the grant)	90 days	run() returns needs_connection; 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.

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.
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.

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://api.paygent.payman.ai/openapi/paygent-cloud-api.yaml

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

curl -s https://api.paygent.payman.ai/connect/tool-definition | jq .version