Error handling

Error shape

When something fails, REST responses usually look like one of these:

{
  "error": {
    "type": "invalid_request_error",
    "message": "content is required",
    "param": "content"
  }
}

{
  "detail": "content is required"
}

For full status code and error-type mapping, use API errors reference.

What fields mean

Field	Meaning
`type`	Broad error category
`message`	Human-readable reason
`param`	Which input field caused the problem (if available)
`code`	Optional machine-friendly error code

SDK try/catch

import { AmarsiaSdkError } from "@amarsia/sdk"

try {
  await client.run({
    content: [{ type: "text", text: "Hello" }],
  })
} catch (error) {
  if (error instanceof AmarsiaSdkError) {
    console.error(error.name, error.status, error.code, error.message)
    console.error(error.details)
  } else {
    console.error(error)
  }
}

SDK-thrown validation errors

Some errors happen before the request reaches the API:

content is empty or malformed
conversation continuation includes variables or meta
message history requested without conversation id

Streaming fallback

If streaming fails:

retry once
if still failing, call regular endpoint
show full answer when it completes

This keeps UI reliable.