Retries & fallback

createSandboxClient owns retry and provider fallback. Both are driven by the retryable flag on SandboxError.

Retry policy

By default the client retries up to twice (3 attempts total) on retryable errors, with exponential backoff. Override per-client:

const client = createSandboxClient({
  provider: e2b({ apiKey }),
  retry: {
    retries: 4,
    delayMs: (attempt) => attempt * 250,
    shouldRetry: (err) => isRetryableError(err),
  },
});

Provider fallback

Supply a fallback chain and the client will try the next provider when one fails:

const client = createSandboxClient({
  provider: e2b({ apiKey }),
  fallback: [vercel({ token, teamId, projectId })],
});

Fallback engages only when you pass an idempotencyKey on the create spec. This is deliberate: without a stable key, a create that failed after spawning a VM could leave an orphan when the client moves to the next provider. The key makes the operation safe to re-attempt.

const sandbox = await client.create({
  idempotencyKey: "build-job-42",
});

If every provider in the chain fails, the client throws AllProvidersFailedError with the per-provider attempts[].

Hooks

Observe the lifecycle with hooks — handy for logging which provider served a request, or recording retry attempts:

const client = createSandboxClient({
  provider: e2b({ apiKey }),
  hooks: {
    beforeCreate: (spec) => {
      /* ... */
    },
    afterCreate: ({ id, provider }) => {
      /* ... */
    },
    onError: (err, attempt) => {
      /* ... */
    },
  },
});