Response signals and errors

This is the reference for what Lasso Cloud adds to responses and the errors it returns. Every error Lasso originates names its fix in next_action. For how to use these signals together, read routing evidence.

"error": {
  "code": <JSON-RPC code>,
  "message": "…",
  "data": {"code": "balance_exhausted", "next_action": "POST https://lasso.sh/api/v1/accounts/…/credit, or subscribe"}
}

Response headers

Header	Meaning
`x-lasso-request-id`	Unique per request; quote it when reporting a problem
`x-lasso-access`	What served the request: `premium`, `public` or `custom`
`x-lasso-fallback`	Present only when the request was served somewhere other than the profile it named: `payment`, `free` or `profile`
`x-lasso-cu`	The request’s size in compute units
`x-lasso-usd`	The request’s charge to the balance in USD; `0` when included usage, free access, Custom access or payment fallback covered it
`x-lasso-balance-usd`	An estimate of the balance after this charge. `GET /api/v1/accounts/{id}` is authoritative
`RateLimit-Policy`, `RateLimit`	IETF rate-limit fields, named after the bucket that bound the request: `managed`, `public` or the Custom profile’s slug
`x-lasso-meta`	With `include_meta=headers`: unpadded base64url JSON of `lasso_meta`

`x-lasso-fallback`	Why
`payment`	The account’s paid spending ran out within its grace window; served on public providers, uncharged
`free`	Served on public providers under the account’s free monthly allowance
`profile`	The named Custom profile was deleted or its Custom access lapsed; served as `premium`

`lasso_meta`

Add ?include_meta=body for a top-level lasso_meta object, or ?include_meta=headers for the x-lasso-meta header. Lasso Cloud returns:

Field	Meaning
`strategy`	The strategy actually used; differs from the URL when the serving access doesn’t allow the one requested
`chain_id`	The chain served
`candidate_providers`	Providers considered, in order; not a list of attempts
`selected_provider`	The provider that served the request
`upstream_latency_ms`	Time spent at the provider
`lasso_overhead_ms`	Time spent in Lasso
`retries`	Attempts after the first

Read serving access and fallback from the x-lasso-access and x-lasso-fallback headers. Managed providers appear under public aliases; Custom profiles show your provider names. The routing engine’s full field list, including block protection fields, is in request metadata. WebSocket callers add "lasso_meta": "notify" to a request for a follow-up lasso_meta notification.

RPC errors

RPC errors stay standard JSON-RPC. Errors Lasso originates carry error.data.code, error.data.next_action and error.data.retryable. A retryable error with Retry-After is safe to repeat as is after the wait. These are the requests Lasso answers itself, before routing:

Code	HTTP	Retryable	Fix
`key_revoked`	401	No	Use the current key.
`unauthorized`	401	No	Supply an enabled RPC key.
`unavailable`	503	Yes	Retry shortly.
`not_prepared`	503	Yes	Retry shortly.
`profile_config_unavailable`	503	Yes	Retry shortly.
`forbidden`	403	No	Use an allowed profile.
`unknown_profile`	404	No	Use a known profile slug.
`unknown_chain`	400	No	Choose a chain from /agent.json.
`balance_exhausted`	402	No	Credit the account or restore its allowance.
`invalid_field`	400	No	Use /profile/<slug>/<strategy>/<chain> or /<chain>.
`invalid_request`	400	No	Send a bounded JSON-RPC envelope.
`rate_limit_exceeded`	429	Yes	Retry after the indicated delay.

Errors from providers pass through unchanged. When every eligible provider fails, the final JSON-RPC error arrives in an HTTP 200 response. An eth_getLogs range a provider refuses as too large returns -32005 with data.code: "log_range_limit"; split the range and retry.

WebSocket close reasons

Close reason	Cause	Fix
`balance_exhausted`	The account stopped being served	Credit the account, then reconnect
`custom_access_expired`	Custom access lapsed on this profile	Reconnect; the managed pool serves you until access is renewed
`default_profile_changed`	The key’s default profile changed	Reconnect; the new default serves you
Code 1011	Subscription recovery after a provider failure exceeded its bounds	Reconnect and resubscribe

Revoking a key, or the end of a rotation overlap, closes sockets using that secret.

Management API errors

Management errors use one envelope:

{"error": {"code": "unknown_chain", "message": "No chain named 'mainnet'.",
  "next_action": "Use a name or ID from /agent.json chains, such as 'ethereum'.",
  "docs_url": "https://docs.lasso.sh/…"}}

Code	HTTP	Fix
`unauthorized`	401	Send the management token from POST /api/v1/keys as Authorization: Bearer <token>.
`payment_invalid`	402	Repeat the request without payment for a fresh challenge, sign it, and send the same body with the signature.
`payment_required`	402	Sign one challenge with an x402 or MPP client and repeat this request with PAYMENT-SIGNATURE or Authorization: Payment.
`custom_access_required`	403	Buy days with POST /api/v1/accounts/{id}/custom-access for one of the account’s keys, or subscribe at https://lasso.sh/pricing, then retry.
`forbidden`	403	Ask the account owner for a token that grants it.
`not_found`	404	Check the ID; resources outside the token’s scope look absent. List keys with GET /api/v1/keys.
`account_merged`	409	Create the profile from the account it was merged into.
`already_claimed`	409	Manage the key with a token from the owning account.
`already_subscribed`	409	Use Custom profiles directly; no purchase is needed.
`beneficiary_conflict`	409	Don’t pay again. Keep the purchase ID and signed payment, report the key with POST /api/v1/feedback so its owner can be reconciled, then retry the same request.
`key_limit`	409	Delete an unused key with DELETE /api/v1/keys/{id}, then retry.
`key_revoked`	409	Create a new key with POST /api/v1/keys.
`payment_conflict`	409	Check the first payment at its status_url; never sign a second payment while one is pending.
`payment_failed`	409	Repeat the request without payment for a fresh challenge.
`profile_limit`	409	Delete an unused profile with DELETE /api/v1/profiles/{slug}, or subscribe to a larger plan.
`profile_suspended`	409	Restore Custom access to reactivate it, or delete it with DELETE /api/v1/profiles/{slug} and apply the document again.
`revision_conflict`	409	Read it again with GET /api/v1/profiles/{slug}, then reapply.
`gone`	410	Create keys with POST /api/v1/keys. Existing keys keep working; use Authorization: Bearer <RPC key> with POST /api/v1/accounts/current/claim-link to claim one.
`amount_out_of_range`	422	Stay within the per-purchase range or day range listed in /agent.json.
`invalid_config`	422	Correct each field path listed in details, then retry.
`invalid_field`	422	Replace {id} with an ID the API returned, such as an account_id or purchase id.
`provider_check_failed`	422	Fix or remove the URL of provider ‘<provider>’, then retry.
`unknown_chain`	422	Use a chain name or decimal ID from /agent.json chains, such as ‘ethereum’ or ‘8453’.
`unknown_field`	422	Remove ‘<field>’; /openapi.json lists the fields each operation accepts, and internal settings are Lasso-managed.
`rate_limited`	429	Wait for Retry-After, then retry.
`payment_pending`	503	Do not pay again; Lasso completes this payment in the background. Check its status_url.
`unavailable`	503	Retry later; /agent.json lists the operations that are enabled.

Exact response schemas are in openapi.json.

Routing evidence: use these signals to debug.
Upgrading from Agent API v2: older headers and error fields.

Start here

Concepts

Guides

Reference

Response signals and errors

Response signals and errors

Response headers

`lasso_meta`

RPC errors

WebSocket close reasons

Management API errors

Next

​Response signals and errors

​Response headers

​lasso_meta

​RPC errors

​WebSocket close reasons

​Management API errors

​Next

Response signals and errors

Response headers

`lasso_meta`

RPC errors

WebSocket close reasons

Management API errors

Next