Errors

Every error the Fleet API and the Fleet SDK layer return, with its cause and fix. SDK languages surface them as CuaError cases, named in each entry.

HTTP status codes#

Errors from the gateway carry {"error": "<message>"}; errors from the Kubernetes proxy carry a Kubernetes Status object with message and reason.

HTTP 400#

The request is malformed: a missing field, a bad name, or a value out of range.

Fix: Check the body against the object reference; the error message names the field.

HTTP 401#

No token, or an expired or invalid one.

Fix: Send Authorization: Bearer <token> with a fresh token from your API key.

HTTP 403#

The token is valid but may not act on this namespace, or the proxy does not allow this request. On a read, Fleet answers 403 for a namespace that no longer exists; on a pool write, the pool name belongs to another account.

Fix: Check the namespace and name. For a new pool, pick another pool name (names are unique across accounts).

HTTP 404#

The object does not exist.

Fix: Check the name and namespace; list the collection to see what exists.

HTTP 409#

An object with that name exists.

Fix: Use another name, or read the existing object.

HTTP 500#

Fleet failed to process the request.

Fix: Retry; report persistent failures with the request and time.

HTTP 502#

Fleet could not reach the backend behind the gateway (the Kubernetes API or the sandbox service).

Fix: Retry. For a service URL, check that the sandbox is bound and its service is listening.

HTTP 503#

The feature is not configured in this environment (for example signed service URLs).

Fix: Use the SDK service URL instead, or contact support.

SDK errors#

Raised by the Fleet layer of the SDK (cua_fleet::Error).

MissingCredentials#

No Fleet credentials: neither a cua auth login session, FLEETS_TOKEN nor CUA_CLIENT_ID + CUA_CLIENT_SECRET (MISSING_CREDENTIALS). Run cua auth login, set the client credentials, or run the sandbox locally.

Fleet credentials missing: run `cua auth login` or set CUA_CLIENT_ID/CUA_CLIENT_SECRET, or pass local=True

Surfaces as CuaError.ProviderNotConfigured.

InvalidArgument#

A value the SDK checks before calling Fleet is invalid (a name that is not a DNS label, a bad secret, an unusable spec). The message names the value; fix it and retry.

invalid argument: <0>

Surfaces as CuaError.InvalidArgument.

Sdk#

The Fleet API call failed: an HTTP status, a transport or token failure, or an unexpected body (SdkError, listed under Fleet API client errors).

Surfaces as CuaError.NotFound (a missing object), else CuaError.Fleet.

AdmissionDenied#

Fleet's admission refused a write: a sandbox size or pool size over this account's limits, or a template its policy does not admit. The message is Fleet's own and names the limit. Change the value, or ask Cua support to raise the account's limits.

Fleet refused <operation> (HTTP <status>): <message>

Surfaces as CuaError.FleetAdmissionDenied.

CreditExhausted#

The account is out of Cua Cloud credit: no credit left, and no card or plan (Fleet answers HTTP 402 cloud_credit_exhausted). Running sandboxes keep running; new ones are refused. Add credit (a plan or a card for pay as you go) on the page at billing_url.

<message> Add credit at <billing_url>

Surfaces as CuaError.CloudCreditExhausted.

UnknownService#

The claim's sandbox does not expose the service. Use one of the services its template declares (available), or add the service to the pool's template.

sandbox <sandbox> exposes no service <service> (available: <available>)

Surfaces as CuaError.NotFound.

Timeout#

A wait ran out: a pool that never became ready, or a claim that never bound. Check the pool's ready replicas and capacity, then retry with a longer timeout.

timed out: <0>

Surfaces as CuaError.Timeout.

Env#

The claimed sandbox's cua-spacesd failed or is unreachable.

Surfaces as CuaError.SpacesdNotAvailable, CuaError.Unauthenticated, CuaError.InvalidArgument, CuaError.Timeout, CuaError.Transport, CuaError.Env.

Unsupported#

The runtime or this Fleet release cannot run what the spec asks (for example env on a KubeVirt pool). The message names the field; drop it or pick a runtime that supports it.

unsupported: <0>

Surfaces as CuaError.Unsupported.

PoolSpecMismatch#

Surfaces as CuaError.PoolSpecMismatch.

ClaimSecretsNotDelivered#

Surfaces as CuaError.ClaimSecretsNotDelivered.

Fleet API client errors#

The Fleet API client under the SDK (SdkError). They reach SDK callers through Sdk above: as CuaError.NotFound for a missing object, otherwise CuaError.Fleet, with this message.

Configuration#

invalid configuration: <reason>

InvalidResourceName#

invalid <field> <value>: <reason>

Transport#

transport error: <reason>

Token#

token error: <reason>

Body#

invalid response body: <reason>

Status#

<operation> returned HTTP <status>: <body>

SignedServiceUrlsUnavailable#

signed service URLs are not configured in this environment

SdkError.UnknownService#

unknown sandbox service <requested>; available services: <available>

InvalidServicePath#

invalid service path: <path>

ClaimFailed#

claim entered terminal phase <phase>: <status>

ClaimTimeout#

claim did not bind before the polling limit

PoolAccessDenied#