Skip to content

Errors

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:

FieldMeaning
request_idRequest identifier. Supports recovery on commands with request-ID replay.
operation_idAccepted operation to read.
retry_afterDelay in seconds before another attempt.
actionSuggested next action.
urlPayment 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

#
KindAction
unauthenticatedSupply a valid credential. It can be missing, expired or revoked.
deniedCheck command permissions and access to the target.
not_foundCheck the name, organization and credential scope. Inaccessible resources can produce this error.
invalidCorrect the named field or value.
conflictRead 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 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 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, retain the error kind, message and request or operation IDs. HTTP also returns Heaven-Request-Id.

Codes

#
CodeStatusChangedWhat happened
invalid400NoAn input is missing or invalid. Correct the input named in message.
unauthenticated401NoThe credential is missing, invalid, expired or revoked. Sign in again or supply a valid credential.
denied403NoThe caller lacks permission for this action. Check command permissions, resource scope and the caller's role.
not_found404NoThe resource is absent or inaccessible to this caller. Check the name or ID, organization and access scope.
conflict409NoThe request conflicts with the current resource state or an earlier request. Read message and the current resource to resolve the conflict.
over_capacity409NoThe request exceeds a resource or credential allowance. Address the allowance named in message.
access_list_full409NoThe change would exceed the access-list allowance. Reduce access entries or use a team or organization share.
payment_required402NoPayment or credit is required. Follow message or the returned payment url, then retry after payment.
rate_limited429NoThe caller's request rate exceeds its limit. Wait at least retry_after seconds before retrying.
busy429NoToo much work is in progress to accept this request. Wait for retry_after seconds when supplied, or retry after a short delay.
unknown503MaybeThe 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.
unavailable503NoThe service or requested feature is unavailable. Read message. Retry temporary failures later.