# Errors

URL: https://heaven.dev/docs/reference/errors
Updated: 2026-11-21

Heaven returns structured errors for refused requests and uncertain outcomes. `error.kind` identifies the condition; `error.message` explains it. Programs should branch on the kind.

## Error fields

A management error contains `version: 1` and an `error` object. Additional fields depend on the error:

| Field | Meaning |
| --- | --- |
| `request_id` | Request identifier. Supports recovery on commands with request-ID replay. |
| `operation_id` | Accepted operation to read. |
| `retry_after` | Delay in seconds before another attempt. |
| `action` | Suggested next action. |
| `url` | Payment link, when payment is required. |

CLI and SSH errors go to standard error, or to standard output with `--json`. MCP marks refusals with `isError`.

## Causes

| Kind | Action |
| --- | --- |
| `unauthenticated` | Supply a valid credential. It can be missing, expired or revoked. |
| `denied` | Check command permissions and access to the target. |
| `not_found` | Check the name, organization and credential scope. Inaccessible resources can produce this error. |
| `invalid` | Correct the named field or value. |
| `conflict` | Read the current resource and the error message to resolve the conflicting name, state or request ID. |

## Retries and recovery

Retry a refused request after resolving its cause. For `rate_limited` or `busy`, wait for `retry_after` seconds when supplied; HTTP also returns `Retry-After`.

An `unknown` outcome means the change may have happened. A lost connection requires the same care:

- With an operation ID, [read the operation](https://heaven.dev/docs/reference/operations/read) to follow the accepted work.
- With a supported request ID, repeat the original inputs and ID: `Idempotency-Key` over HTTP, `--request-id` in CLI or SSH, or `request_id` in MCP. A new ID can start new work.
- Without request-ID support, inspect the resource before repeating the action. After losing an API-key creation response, list keys and revoke the unseen key before creating another.
- For a guest command, inspect its effects inside the Computer before running it again.

Ordinary reads can be repeated after transient failures. If an operation wait expires, repeat the read. See [HTTP recovery](https://heaven.dev/docs/http-api#lost-responses-and-errors) for retaining request identity.

## Operation results

HTTP `200` confirms a successful request; the response can still describe unfinished or partly failed work. Follow returned operations and individual target results.

A `failed` operation contains its error. A `superseded` operation was replaced by newer work; read the resource's current state.

For [support](https://heaven.dev/docs/support), retain the error kind, message and request or operation IDs. HTTP also returns `Heaven-Request-Id`.

## Codes

| Code | Status | Changed | What happened |
|---|---:|---|---|
| `invalid` | 400 | No | An input is missing or invalid. Correct the input named in `message`. |
| `unauthenticated` | 401 | No | The credential is missing, invalid, expired or revoked. Sign in again or supply a valid credential. |
| `denied` | 403 | No | The caller lacks permission for this action. Check command permissions, resource scope and the caller's role. |
| `not_found` | 404 | No | The resource is absent or inaccessible to this caller. Check the name or ID, organization and access scope. |
| `conflict` | 409 | No | The request conflicts with the current resource state or an earlier request. Read `message` and the current resource to resolve the conflict. |
| `over_capacity` | 409 | No | The request exceeds a resource or credential allowance. Address the allowance named in `message`. |
| `access_list_full` | 409 | No | The change would exceed the access-list allowance. Reduce access entries or use a team or organization share. |
| `payment_required` | 402 | No | Payment or credit is required. Follow `message` or the returned payment `url`, then retry after payment. |
| `rate_limited` | 429 | No | The caller's request rate exceeds its limit. Wait at least `retry_after` seconds before retrying. |
| `busy` | 429 | No | Too much work is in progress to accept this request. Wait for `retry_after` seconds when supplied, or retry after a short delay. |
| `unknown` | 503 | Maybe | The outcome is unconfirmed; a change may have happened. Retry reads. For changes, read the operation or inspect the resource. Where replay is supported, repeat the original inputs and request ID. |
| `unavailable` | 503 | No | The service or requested feature is unavailable. Read `message`. Retry temporary failures later. |
