> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Retry lifecycle operations safely and preserve provider-shaped errors.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.