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_allowedError 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, patch or file doesn't exist. | Don't retry. |
| conflict | Not possible in the session's current state (e.g. an approval, or a file call, to a paused session), or an idempotency key reused with different settings. | Check the status, then act. |
| limit_reached | The session reached a spend limit. While it wraps up it takes no more messages (approvals and cancel still work); once paused at the cap it does not continue. | Raise the cap with update(), then send a message or resume. |
| patch_too_large | The patch is over 15 MB. | Keep generated files out of the change. |
| request_too_large | A create request is over 50 MB, usually from large files sent inline. | Create without input, upload the files once it is running, then send the message. |
| file_too_large | An upload is over the 1 GiB cap. | Upload a smaller file. |
| attachment_too_large · attachments_too_large | An image named in a message's files is over 5 MiB, or the images together are over 20 MiB. | Send fewer or smaller images, or name the path in the message. |
| session_limit_reached | Your organization is at its cap of live sessions, where one is set. | Delete one, or wait for one to pause. |
| endpoint_limit_reached | You have as many registered webhook endpoints as allowed in this organization. | Delete one first. |
| endpoint_disabled | A test or retry was sent to a webhook endpoint that is turned off. | Turn it on with enabled: true. |
| endpoint_backlogged | A webhook endpoint already has 1,000 deliveries waiting, so no test was queued. | Let them finish or fail first. |
| rate_limited | More than 60 webhook tests and retries in a minute. | Wait a minute. |
| 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 or a file call. | 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, or isn't ready within 240 seconds (
start_timeout), becomesfailed. Create another. - A paused session that can't resume goes back to
pausedwith 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. - A file sent with
fileson create that can't be put in the workspace makes the sessionfailed, with an error of typefiles_errorthat names the file.
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_errorandnetwork_errorare safe to retry with backoff. Pass an idempotency key when retrying a create.conflictwhile 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.