Skip to main content

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.

Response headers

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: 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. balance_exhausted additionally carries error.data.credit_url, the account’s credit endpoint. The catalog covers local refusals and terminal routing outcomes: Provider errors keep their code, message and data. When every eligible provider fails, the final JSON-RPC error arrives in an HTTP 200 response. A provider-reported eth_getLogs range limit tries the remaining candidates with the unchanged query first; only once none of them serve it does Lasso return -32602 with data.reason: "log_range_too_large" and data.action: "reduce_block_range". Split the range and retry. When Lasso’s own retry budget for a read runs out across several providers without a usable response, it returns its own error instead of the last provider’s: -32601 when every attempt was rejected as unsupported, -32005 when every attempt was rate limited or had exhausted its provider allowance, otherwise -32000. error.data.upstream_attempts is how many providers Lasso tried, and error.data.categories breaks that count down by cause; neither upstream identities, messages nor response data are included.

Transaction submission errors

A final routed eth_sendRawTransaction error carries these fields in error.data: The upstream rejection’s code and message stay, with scalar upstream data under upstream_data. Honor any Retry-After. When retryable is true, resend identical signed bytes; changing fees or nonces creates a replacement your app must manage. When retryable is false, check the hash for a receipt before signing a new one. See transaction behavior.

WebSocket close reasons

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

Management API errors

A 202 with Retry-After means Lasso accepted the request and is finishing it. Keep the response, wait, then continue with what it returned; don’t send the request again. Management errors use one envelope:
Exact response schemas are in openapi.json.

Next