---
title: "Errors"
description: "Status codes, reasons and what to do when a call fails."
---

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

# Errors

Sutra uses the standard gRPC status codes, each with its HTTP equivalent. Every error also carries a machine-readable `reason` in `UPPER_SNAKE_CASE` and a `domain` that names the service. Match on the reason in your code, not on the message.

## Common codes

| Code | HTTP | When you see it |
| --- | --- | --- |
| `INVALID_ARGUMENT` | 400 | A field is missing or invalid. The error lists each field. A field Sutra does not support has the reason `FIELD_NOT_SUPPORTED`. |
| `FAILED_PRECONDITION` | 400 | The resource is not in a state that allows the call, such as running a process in a stopped sandbox. |
| `UNAUTHENTICATED` | 401 | The API key is missing, invalid or revoked. |
| `PERMISSION_DENIED` | 403 | The key is valid but not allowed to make the call. The reason says why. |
| `NOT_FOUND` | 404 | The resource does not exist, or you cannot see it. |
| `ALREADY_EXISTS` | 409 | The id is taken, or you reused a `requestId` with a different request. |
| `ABORTED` | 409 | The `etag` you sent no longer matches: the resource changed since you read it. |
| `RESOURCE_EXHAUSTED` | 429 | You reached a quota, or Sutra has no capacity for the request (reason `NO_CAPACITY`). |
| `DEADLINE_EXCEEDED` | 504 | The call ran out of time. |
| `UNAVAILABLE` | 503 | Sutra cannot answer right now. Retry. |
| `INTERNAL` | 500 | Something failed on Sutra's side. |

## Details

Some errors carry more detail:

- **Retry info**: present when a retry can succeed, with how long to wait.
- **Field violations**: on `INVALID_ARGUMENT`, one entry per invalid field.
- **Quota**: on `RESOURCE_EXHAUSTED`, which quota you reached.

The SDKs raise typed errors with `code`, `reason` and these details.

## Unsupported inputs are refused

Sutra refuses an input it does not act on, and a value outside a limit, with `INVALID_ARGUMENT`. It never drops a field or lowers a value without telling you.

## A non-zero exit is not an error

A process that exits with a non-zero code is a result. The call succeeds and returns the exit, and you decide what the code means. See [Processes](https://docs.jgcp.mistrivedev.com/sandboxes/processes/#exit).

:::note[Today]
Today errors carry a status code and a message but no `reason`.

A refused input is `INVALID_ARGUMENT` with the message `<field> is not supported: <advice>`, such as `ttl is not supported: preview links do not expire; leave it unset`. The field is named by its path in the request. Inputs refused today include:

- In a sandbox create: network and egress settings, an image, a node, a snapshot to start from and a profile.
- `signal` and `gracePeriod` on a process `kill`.
- `ttl` on a port's link, and the access mode `SIGNED_URL`.
- A time limit on a file search or replace.
- `requestId` on a volume or snapshot delete.
- An `exec` timeout outside 1 to 300 seconds, and a `maxDuration` under 1 second or over 2147483647 seconds.

Deletes of sandboxes, apps and snapshots, app session creates and stops, and changes to SSH access wait up to 30 seconds for their work. When the wait ends first, the call answers `DEADLINE_EXCEEDED` (HTTP 504) and the work continues. Repeat the call as its message says; the TypeScript SDK repeats sandbox deletes and SSH access changes for you. Other work that is still in progress answers `UNAVAILABLE`: retry it.

A command that times out is `DEADLINE_EXCEEDED`, and one the sandbox cannot run is `FAILED_PRECONDITION`. See [Processes](https://docs.jgcp.mistrivedev.com/sandboxes/processes/).
:::

Source: https://docs.jgcp.mistrivedev.com/reference/errors/index.mdx
