Skip to main content
Lifecycle errors and environment errors are separate layers.

​
Lifecycle errors

​
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. For CREDIT_FLOOR_NOT_MET or INSUFFICIENT_ENVIRONMENT_RUNTIME_CREDITS, run:
If the command prints a Stripe Checkout URL, a workspace owner or admin must complete it in a browser. Run the command again to confirm that usage billing is active, then retry the original session request.