Errors

Handle REST envelopes, SDK errors, durable-agent conflicts, retries, and multiple-browser result races.

Overview

Use HTTP status for broad handling and the nested detail.code or normalized SDK code for durable-agent decisions. Do not blindly retry state conflicts.

REST envelopes

The API can return an OpenAI-style error, a FastAPI detail string, a validation list, or a structured detail object:

{
  "detail": {
    "code": "action_result_conflict"
  }
}

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

HTTP status handling

Status	Meaning	Action
`400`	Invalid body or tool result	Correct the request
`401`	Missing or invalid API key	Fix authentication
`403`	Origin or caller is not allowed	Check security configuration
`404`	Deployment, conversation, or run not found	Verify IDs and ownership
`409`	Current lifecycle conflicts with the request	Refresh state and branch on code
`422`	Request validation failed	Correct field types
`429`	Rate limited	Retry with backoff
`5xx`	Server failure	Retry only when the operation is safe

Durable agent errors

Code	Status	Meaning	Action
`missing_tool_results`	`400`	Not every pending call has a result	Submit all pending call IDs together
`unknown_call_id`	`400`	A result references a non-pending call	Refresh and rebuild the result set
`invalid_tool_result`	`400`	Output does not match the tool contract	Fix the output shape
`client_action_required`	`409`	A new turn was attempted while input is pending	Resolve pending calls
`run_in_progress`	`409`	A new turn was attempted while a run is active	Refresh until it settles
`action_result_conflict`	`409`	Different output was already accepted for these calls	Keep the first accepted result
`conversation_completed`	`409`	The conversation is permanently completed	Show read-only state
`run_expired`	`409`	A non-agent client-tool run expired	Start a new turn

An identical retry of an already accepted tool-result set is idempotent. A different retry conflicts, which protects the first accepted result when several browsers are open.

SDK errors

import { AmarsiaSdkError } from "@amarsia/sdk"

try {
  await client.agent.continue()
} catch (error) {
  if (error instanceof AmarsiaSdkError) {
    console.error(error.status, error.code, error.message, error.details)
  }
}

Error `name`	Meaning
`AmarsiaHttpError`	Non-success API response
`AmarsiaValidationError`	Invalid SDK input or completed-conversation continuation
`AmarsiaConfigurationError`	Missing client, deployment, or conversation context
`AmarsiaAbortError`	Aborted request or lifecycle
`AmarsiaNetworkError`	Network failure

The agent controller also stores normalized error data on client.agent.error. Its conflict handling refreshes current state for common concurrent start and result-submission races.

Retry guidance

Retry 429, transient 5xx, and network failures with bounded backoff.
Retry a tool result only with the exact same call IDs and outputs.
Refresh state before responding to 409.
Do not retry conversation_completed.
After runStatus === "interrupted", call agent.continue() to start a new turn; do not resubmit a changed result.