Skip to content

Errors

Status codes, reasons and what to do when a call fails.

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.

Type to search…

↑↓ navigate↵ selectEsc close