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.