Agents APIReference

Errors

Every failed call raises one error type with a stable name you can branch on.

LatentStackError

Both SDKs raise LatentStackError for every failure. It has a type to branch on, a message written for people, and the HTTP status (0 when no response arrived). Branch on type; messages may change.

Catch and inspect an error

import { LatentStack, LatentStackError } from "@latentcode/sandbox-agents"

const client = new LatentStack({ apiKey: process.env.LS_API_KEY! })
const sessions = client.agents.sessions

try {
  await sessions.get("ags_does_not_exist")
} catch (error) {
  if (!(error instanceof LatentStackError)) throw error
  console.log(error.status, error.type, error.message) // 404 not_found No session 'ags_does_not_exist'.
}

try {
  await sessions.create({ agent: { model: "no-such/model" }, input: "hi" })
} catch (error) {
  if (!(error instanceof LatentStackError)) throw error
  console.log(error.status, error.type) // 403 model_not_allowed
}

404 not_found No session 'ags_does_not_exist'.
403 model_not_allowed

Error types

type	Meaning	What to do
invalid_request	A setting or argument is wrong. The message names it.	Fix the call.
invalid_api_key	The key is missing, invalid or expired, or it isn't an `ls-` API key.	Use a valid API key.
model_not_allowed	Your tier doesn't include the model.	Choose one from `latentcode models`.
no_tier_assigned	Your account has no access tier in this organization.	Ask an administrator.
github_not_connected	A repository session needs a GitHub token.	Add one in Agent Settings.
repo_not_accessible	Your GitHub token can't read a repository. The message names it.	Check the name, or grant the token access.
not_found	The session doesn't exist or isn't yours, or the request, repository or patch doesn't exist.	Don't retry.
conflict	Not possible in the session's current state (e.g. an approval to a paused session), or an idempotency key reused with different settings.	Check the status, then act.
patch_too_large	The patch is over 15 MB.	Keep generated files out of the change.
session_limit_reached	Your organization is at its limit of active sessions.	Delete one, or wait for one to pause.
runner_unavailable	No capacity to start a sandbox right now.	Retry after a short wait.
github_unavailable	GitHub couldn't be reached to check access.	Retry shortly.
container_error	The sandbox didn't accept an input.	Retry.
network_error	The request never got an answer (DNS, TLS, connection).	Retry with backoff.
timeout	`wait()` ran out of time. The session itself is unaffected.	Wait again, or check on it later.

Errors on the session

Some problems happen after your call has returned: a sandbox fails to start, or disappears. These don't raise an error in your code. They show on the session's error field and on session.status items:

A new session whose sandbox can't start becomes failed. Create another.
A paused session that can't resume goes back to paused with the error, and keeps your messages. Send another message to retry.
A session whose sandbox disappears becomes paused, and resumes with its files on the next message.

run.failed is different again: one run stopped on an error, such as the model provider failing. The session is fine; send another message.

Retries

runner_unavailable, github_unavailable, container_error and network_error are safe to retry with backoff. Pass an idempotency key when retrying a create.
conflict while a session is pausing clears in a few seconds.
Everything else needs a change before trying again.
The event stream retries dropped connections on its own and resumes without gaps.