Some calls take a while: creating, starting, stopping and deleting a sandbox, for example. These calls return an operation that tracks the work.
The SDKs wait for you
By default an SDK call waits for its operation and returns the finished resource. Pass wait to limit how many seconds the call waits:
const sandbox = await sutra.sandboxes.create({ id: "build-42", wait: 30 });wait limits only your call. If it ends first, the work continues, and you can read the resource or the operation later.
Operation resources
An operation has the name operations/{operation} under your project. Its metadata names the resource it works on from the start, and when it is done, its response is that resource. You can get, list and wait for operations, and cancel those where it makes sense.
Access to an operation follows its resource: if you can read the sandbox, you can read the operation that creates it.
Retry safely
Every call that changes something takes a requestId. Send the same requestId again and you get the result of the first call instead of a second change. The SDKs generate one for each call, so their own retries are safe. Pass your own when you retry across process restarts:
await sutra.sandboxes.create({ id: "build-42", requestId: "7d1c6a0e-4f0b-4b4e-9c55-3f0a9b8e2d11" });A requestId is any string up to 128 bytes; a UUID works well. Reusing one with a different request fails with ALREADY_EXISTS.
Concurrent changes
Every resource you can change has an etag. Pass it to update, delete, stop or start to make the call fail with ABORTED if someone changed the resource since you read it.