> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lasso.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Response signals and errors

> Every Lasso Cloud response header, lasso_meta field, RPC error code and management API error, with the fix for each

# 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](/cloud/observability).

```text theme={null}
"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](/observability/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:

```json theme={null}
{"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](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`](https://lasso.sh/openapi.json).

## Next

* [Routing evidence](/cloud/observability): use these signals to debug.
* [Upgrading from Agent API v2](/cloud/reference/v2-compatibility): older
  headers and error fields.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.