Errors

REST error envelopes

REST responses can return one of these shapes.

OpenAI-style envelope:

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

FastAPI-style envelope:

{
  "detail": "content is required"
}

FastAPI validation envelope:

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

REST field meaning

Field	Type	Meaning
`type`	string	High-level error category
`message`	string	Human-readable explanation
`param`	string or null	Related request field
`code`	string or null	Stable machine-readable code

HTTP status summary

Status	Name	Meaning	Recommended action
`200`	OK	Request succeeded	Use response
`400`	Bad Request	Invalid request body/params	Fix payload
`401`	Unauthorized	Missing/invalid API key	Fix key header
`403`	Forbidden	Key valid but no access	Check permissions
`404`	Not Found	Resource or path not found	Verify IDs/path
`409`	Conflict	Request conflicts with existing state	Resolve conflict and retry
`429`	Too Many Requests	Rate limit reached	Retry with exponential backoff
`500`/`502`/`503`/`504`	Server Errors	Temporary server issue	Retry safely

SDK error classes

The SDK normalizes errors into typed classes.

SDK error class	When it happens
`AmarsiaHttpError`	API returned a non-2xx response
`AmarsiaValidationError`	SDK-side validation failed (for example empty `content`)
`AmarsiaConfigurationError`	Missing config or required IDs (for example no conversation id)
`AmarsiaAbortError`	Request was aborted
`AmarsiaNetworkError`	Network layer failure

SDK error fields

Field	Meaning
`name`	Error class name
`status`	HTTP status (when available)
`code`	Stable symbolic code
`message`	Human-readable message
`param`	Related request param when available
`details`	Full parsed response body or raw payload

Common SDK code values:

Code	Typical cause
`bad_request`	Invalid payload
`unauthorized`	Missing/invalid API key
`forbidden`	Key or origin not allowed
`not_found`	Resource/path not found
`unprocessable_entity`	Server-side validation failed
`rate_limited`	Request limit exceeded
`internal_server_error`	Server-side failure

SDK error handling

import { AmarsiaSdkError } from "@amarsia/sdk"

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

Retry rules (all tracks)

Retry: 429, 5xx, network timeouts
Do not retry blindly: 400, 401, 403, 404
For streaming errors: retry once, then fallback to regular endpoint

Errors

On this page