> ## 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 | Free credit exhausted or billing blocked   | Follow the returned billing recovery instruction  |
|    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.

For `CREDIT_FLOOR_NOT_MET` or
`INSUFFICIENT_ENVIRONMENT_RUNTIME_CREDITS`, run:

```bash theme={null}
archal workspace billing setup
```

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.