Response objects by credentials.fetch().
Public error classes
Check specific subclasses before
StateMachinesError. A failure code such as invalid_settings belongs to environment.failure.code. It is not the code property of EnvironmentFailedError.
For StateMachinesError, status is the HTTP status or null. A null value can mean no response arrived, local validation failed, or response parsing failed. code can also be null. Neither field alone establishes whether the server accepted a mutation.
fields maps dotted input paths to arrays of messages. requestId identifies a management request when available. retryAfterMs converts the server’s Retry-After value into milliseconds. These properties can be null.
Polling outcomes
wait(id, { status }) checks the target before classifying failure. Waiting explicitly for failed resolves when that status is read. Waiting for running from paused throws UnexpectedStatusError because resumption needs a separate call.
Environment waits understand starting, running, paused, failed, and deleted. Snapshot waits understand saving, ready, failed, and deleted. An unfamiliar response status is polled until the target or deadline, allowing for server states introduced after this SDK.
Polling retries connection failures, read timeouts, and HTTP 502, 503, and 504 with backoff. A Retry-After value can delay the next poll. Other HTTP failures, such as authentication or validation failures, stop the wait. Each poll read times out after 30 seconds or at the wait deadline, whichever comes first. The polling loop owns its retries rather than nesting the generated client’s retry loop.
Timeout and cancellation
attemptTimeoutMs is a constructor option for each management HTTP attempt. timeoutMs is an option for the wait as a whole. In create and resume helpers, the wait begins after the initial operation succeeds. timeoutMs defaults to 600000. A negative value throws RangeError. Zero expires without reading the resource.
Aborting an explicit wait rejects with the caller’s signal.reason. Aborting the initial management request rejects with StateMachinesError, whose cause records the abort. Application code can check its own signal’s aborted state to distinguish cancellation from another failure.
Cancellation and timeout stop observation. They do not delete an environment, stop snapshot saving, or reverse a resume. Recovery describes how to retain IDs and resume observation.
Management error codes
The SDK’sErrorCode type and openapi.json contain the full error vocabulary. Codes relevant to environment work include:
A code is not a general instruction to retry. The SDK retries a management call after a connection failure, an attempt timeout, or HTTP 502, 503 or 504. It backs off from 1 second to 5 seconds and stops retrying after 10 minutes. It does not retry any 4xx status, 429 or 500. It never retries native app requests.
Error messages avoid embedding raw management response bodies. Application logs still need to exclude credential objects, custom fetch inputs, and bearer headers.