Errors and retries

Lifecycle errors and environment errors are separate layers.

Lifecycle errors

Status	Meaning	Recommended action
400	Invalid shape, state, or environment	Fix the request
401	Missing or invalid workspace key	Replace the key
402	Trial credit exhausted or billing blocked	Stop create retries and inspect the returned code
403	Missing scope or environment grant	Check key access
404	Session is absent or outside the workspace	Stop polling
409	State conflict or idempotency mismatch	Use the original request or a new idempotency key
413	State or request body is too large	Reduce the payload
429	Workspace, key, or session request limit	Respect `Retry-After` and back off
5xx	Control-plane or hosted runtime failure	Retry only safe operations with jitter

Environment errors

Provider-shaped endpoints preserve the environment’s HTTP status and response body. A GitHub 422 remains a GitHub 422. Do not convert it into a generic Archal retry.

Retry rules

Add an idempotency key to every create request
Retry GET and HEAD with bounded exponential backoff
Retry a mutation only when its provider operation is idempotent
Cap attempts and request timeouts
Stop polling on a terminal lifecycle state
Preserve request IDs, response bodies, and teardown errors in test output

The TypeScript client retries a small set of transient statuses. If waiting for a newly created session fails, it attempts cleanup and preserves the original readiness error; a cleanup error is not returned separately. If your workflow must confirm cleanup, use startSession, then call awaitSessionReady and destroySession explicitly in your own try/finally boundary. TRIAL_CREDITS_EXHAUSTED is terminal for new sandbox creation during the current self-serve launch. Stop retrying the create request. The one-time trial credit does not renew, and paid continuation is not yet available. Treat the legacy CREDIT_FLOOR_NOT_MET and INSUFFICIENT_ENVIRONMENT_RUNTIME_CREDITS codes the same way. Do not retry them as transient failures or run billing setup commands.

Guides

OpenAPI

Errors and retries

Lifecycle errors

Environment errors

Retry rules

​Lifecycle errors

​Environment errors

​Retry rules

Lifecycle errors

Environment errors

Retry rules