Errors

Every non-2xx response from the engine returns the same envelope:

{
  "error": {
    "code": "not_found",
    "message": "Registered agent \"does-not-exist\" was not found.",
    "details": null,
    "correlation_id": "6817694a-b7dd-4f0f-8173-83206e1632ac"
  }
}

Status codes

400 — validation error

The request was malformed or missing required fields. details is often an array of human-readable validation messages (e.g. agent registration collects every violation rather than failing on the first one).

404 — missing resource

The resource doesn't exist — or belongs to a different tenant. The engine returns 404, not 403, for a cross-tenant lookup, to avoid leaking whether a resource exists at all. See Security.

409 — lifecycle/state conflict

The request conflicts with the resource's current state — e.g. activating an already-active agent, submitting a task outside an agent's allowed_tasks, or approving a session that isn't awaiting review.

Managed execution (Initiative 2/3) — POST /runtime/agents/{id}/execute records a managed_execution_configuration_rejected event with a stable reason_code whenever its ordered resolution gate rejects a request (see Execution Profiles):

reason_code	Meaning
agent_not_found (404)	The agent_id doesn't exist under the resolved tenant.
agent_not_executable	The agent isn't active.
execution_profile_id_missing	The agent has no execution_profile_id configured.
execution_profile_not_found (404)	The referenced execution_profile_id isn't registered under this tenant — including if it belongs to a different tenant.
execution_profile_not_active	The profile isn't active (e.g. draft or disabled).
adapter_id_missing	The execution profile has no adapter_id configured.
provider_connection_id_missing	The execution profile has no provider_connection_id configured.
adapter_not_found (404)	The referenced adapter_id isn't registered.
adapter_unavailable	The adapter isn't currently available.
connection_not_found (404)	The referenced provider_connection_id isn't registered under this tenant — including if it belongs to a different tenant.
connection_not_valid	The connection isn't valid (e.g. pending, invalid, disabled, deleting).
provider_mismatch	The execution profile's provider doesn't match the connection's provider.
adapter_provider_mismatch	The adapter's provider doesn't match the execution profile's provider.
task_or_mode_unsupported	The adapter doesn't support the requested task type or execution mode.
task_not_allowed_for_agent	The task isn't in the agent's own allowed_tasks.
model_not_configured	The execution profile has no model configured.
endpoint_invalid	The connection's endpoint configuration is malformed.
credential_unresolvable	The stored credential could not be retrieved.
provider_not_implemented (400)	The connection's provider has no managed-execution adapter implementation yet.

500 — internal error

The engine failed unexpectedly. The response never includes internal details beyond a generic message and the correlation id — use that correlation id (also in the X-Correlation-ID response header) when reporting the issue; it's present in the engine's structured logs too.

SDK error classes

Every SDK failure is a subclass of RuntimeSdkError:

RuntimeSdkError
├── RuntimeSdkConfigError     — bad client config (e.g. missing baseUrl); thrown synchronously
├── RuntimeNetworkError       — request never reached the engine (timeout, DNS, connection refused)
├── RuntimeResponseError      — engine responded with a non-JSON or empty body
└── RuntimeApiError           — engine responded with a non-2xx status
    ├── RuntimeBadRequestError       (400)
    ├── RuntimeNotFoundError         (404)
    ├── RuntimeConflictError         (409)
    ├── RuntimeInternalError         (500)
    └── RuntimeUnexpectedStatusError (anything else)

Every instance carries .correlationId when known. RuntimeApiError subclasses also carry .statusCode, .code, and .details.

Retryable vs. non-retryable

Error	Retryable?	Why
RuntimeNetworkError	Yes — with backoff	Transient network/timeout issue
RuntimeInternalError (500)	Yes — with backoff	May be a transient engine fault
RuntimeBadRequestError (400)	No	Fix the request first
RuntimeNotFoundError (404)	No, unless the resource is expected to appear (e.g. eventual consistency isn't a concern here — the engine is strongly consistent)	The resource genuinely doesn't exist
RuntimeConflictError (409)	Sometimes	Depends on the conflict — e.g. an agent that's suspended won't resolve itself; a session state conflict might, once the operator acts
RuntimeSdkConfigError	No	Fix your client configuration

try {
  await runtime.submitAgentRun(input);
} catch (err) {
  if (err instanceof RuntimeNetworkError || err instanceof RuntimeInternalError) {
    // safe to retry with backoff
  } else {
    throw err; // fix the request/state instead
  }
}