Errors & recovery

Decide whether to fix, ask, refresh, or reconcile

An error code is useful only when it leads to the right next action. First distinguish startup exceptions from operation results. Invalid YAML rejects runtime creation; an expired choice is normally returned as an AgentResult with status: "error".

For a mapping/config error, stop and fix the contract. For invalid user input, explain the field constraint. For an expired selection, retrieve fresh choices. For 401/403, use your login/permission UX. For a potentially delivered write, reconcile its backend state before proposing another attempt.

Trace a timeout after approval

Imagine the booking POST is accepted, but the response is lost. Retrying a new invocation could create another booking. Check error.details.executionMayHaveOccurred, your idempotency record, and the API's operation-status lookup. Do not treat an error result as proof of zero side effects.

By contrast, a missing field before any tool call has not sent that write. Use meta.toolCalls and lifecycle events to understand the stage, while treating uncertainty conservatively when the runtime reports it.

Window exhaustion returns RATE_LIMITED; the session lifetime cap returns RATE_SESSION_LIMIT. A downstream 429 returns TOOL_RATE_LIMITED. These need different operational fixes: host budgeting versus upstream capacity.

Use the tables below as a lookup after you identify the failing boundary. Troubleshooting starts from symptoms.

Error result shape

Runtime operations return errors as data:

{
  "status": "error",
  "error": {
    "code": "AUTH_REJECTED",
    "category": "AUTH",
    "message": "Upstream API rejected the request.",
    "details": {
      "status": 401
    }
  }
}

Configuration/startup failures throw AgentRuntimeError because the runtime could not safely initialize.

Common configuration errors

Code	Meaning / next action
`CONFIG_INVALID`	YAML/shape is invalid or multiple config sources were supplied.
`CONFIG_SCHEMA_INVALID`	A tool JSON Schema is unsupported/unsafe.
`CONFIG_SECRET_MISSING`	Required provider/service secret is absent.
`CONFIG_AUTH_INVALID`	Unsafe auth/transport configuration.
`CONFIG_URL_INVALID`	Tool URL violates runtime safety rules.
`CONFIG_MAPPING_INVALID`	Mapping conflicts or reads undeclared data.
`CONFIG_DEPENDENCY_INVALID`	Dependency target/source violates the contract.
`CONFIG_DEPENDENCY_CYCLE`	Automatic dependency graph is cyclic.
`CONFIG_CONFIRMATION_INVALID`	An effectful tool lacks required confirmation.

Routing/model errors

Code	Meaning / next action
`MODEL_NOT_CONFIGURED`	`chat()`/AI presentation requires a model.
`MODEL_PROVIDER_ERROR`	Provider boundary failed.
`MODEL_RESPONSE_MALFORMED`	Provider/model response could not be safely parsed.
`MODEL_SCHEMA_VIOLATION`	Tool selection/arguments violated the expected schema.
`MODEL_TOOL_SELECTION_FAILED`	Model selected outside the allowed candidate set.
`ROUTING_NO_MATCH`	No tool matched while conversation mode is disabled.

Input/continuation errors

Code	Meaning / next action
`INPUT_SCHEMA_VIOLATION`	Supplied arguments violate tool schema.
`INPUT_SELECTION_STALE`	Pending selection expired or no longer matches context. Refresh options.
`INPUT_SELECTION_INVALID`	Choice is not from the current option set.
`CONFIRMATION_STALE`	Confirmation expired or prepared operation/context changed. Rebuild the action.

Auth/session errors

Code	Meaning / next action
`AUTH_REQUIRED`	Required service credential is unavailable.
`AUTH_REJECTED`	Downstream API returned 401/403. Host decides login/permission UX.
`SESSION_ID_INVALID`	Session ID format is invalid.
`SESSION_EXPIRED`	Session TTL expired or config changed. Start a fresh flow.
`SESSION_CAPACITY`	In-memory session capacity was reached. Use cleanup/shared storage.
`SESSION_RUNTIME_DISPOSED`	Runtime was disposed. Stop sending requests to it.

Tool/transport errors

Code	Meaning / next action
`TOOL_ABORTED`	Host cancellation/abort signal.
`TOOL_TIMEOUT`	Upstream exceeded timeout.
`TOOL_NETWORK_ERROR`	Transport failed before a safe response.
`TOOL_REDIRECT_BLOCKED`	Upstream attempted a redirect. Fix configured endpoint.
`TOOL_CLIENT_ERROR`	Non-auth 4xx. Inspect API contract/business input.
`TOOL_RATE_LIMITED`	Upstream returned 429. Retry only under your policy.
`TOOL_SERVER_ERROR`	Upstream 5xx. May participate in safe retries/circuit breaker.
`TOOL_RESPONSE_MALFORMED`	Declared JSON response was malformed.
`TOOL_OUTPUT_LIMIT`	Response exceeded byte ceiling.
`TOOL_OUTPUT_SCHEMA_VIOLATION`	Response violated declared output schema.
`TOOL_CIRCUIT_OPEN`	Circuit breaker is open.
`TOOL_EXECUTION_UNCERTAIN`	A previous effect may have reached the backend. Reconcile before retrying.

Never retry an uncertain business effect blindly

If an error reports details.executionMayHaveOccurred: true or TOOL_EXECUTION_UNCERTAIN, do not equate “the client did not receive success” with “the backend did nothing.” Query operation state or reconcile using your idempotency/audit model.

Error messages are intentionally bounded

AGENTO avoids exposing arbitrary provider/API response bodies as error details. Keep sensitive operational logs in your own trusted infrastructure, not in user-facing messages.