Enum ApiError 

pub enum ApiError {
    BadRequest(String),
    Unauthorized,
    UnknownRun(String),
    UnknownAgent(String),
    RunExists(String),
    WrongState(String),
    MissingDriveToken(String),
    InvalidDriveToken(String),
    UnsupportedEventKind(String),
    Divergence(String),
    PayloadTooLarge(String),
    ModelExecutorUnavailable(String),
    ModelExecution(String),
    UnknownTool(String),
    ToolRegistryUnavailable(String),
    ToolExecution(String),
    InvalidGraph {
        message: String,
        errors: Value,
    },
    UnknownGraph(String),
    NotAGraphRun(String),
    InvalidForkNode(String),
    OriginNeedsReconciliation {
        message: String,
        intent: Value,
    },
    WriteReplayHazard {
        message: String,
        writes: Value,
    },
    NeedsReconciliation {
        message: String,
        intent: Value,
    },
    Internal(String),
}

A control-plane error, with the HTTP status and machine code baked in.

Variants

BadRequest(String)

A request body was malformed, or a resume input failed validation against the recorded schema. HTTP 400.

Unauthorized

The bearer token was missing or wrong. HTTP 401.

UnknownRun(String)

No run exists under the given id. HTTP 404.

UnknownAgent(String)

No agent is registered under the given id. HTTP 404.

RunExists(String)

A run already exists at the requested id. HTTP 409.

WrongState(String)

A verb was applied to a run in the wrong state (resuming a finished run, resolving a run that has no dangling write). HTTP 409.

MissingDriveToken(String)

A client-driven append arrived with no drive token. HTTP 401. The drive token is the per-run single-writer lease; every append must present it.

InvalidDriveToken(String)

A client-driven append presented a drive token that is not the run’s current lease. HTTP 403. Only the run’s current writer may drive it.

UnsupportedEventKind(String)

A client-driven append carried an event kind this endpoint does not accept (a model or tool event, which the model-step and tool-step endpoints own). HTTP 422.

Divergence(String)

A client-driven append is not the legal next event for the run’s log: the re-folding append-guard rejected it, or byte-different bytes arrived at an already-recorded position. HTTP 409.

PayloadTooLarge(String)

A request body exceeded the size or count cap. HTTP 413.

ModelExecutorUnavailable(String)

A server-performed model step was requested but no model executor is wired on this server (the host injected none). HTTP 503. Recording no completion, so the run stays drivable once an executor is present.

ModelExecution(String)

The provider call for a model step failed. HTTP 502. No completion is recorded, so the write-ahead intent is left dangling (the legal crash story) and the run stays drivable: a retry re-issues the call safely.

UnknownTool(String)

A tool-step named a tool the server’s registry does not hold. HTTP 404. Nothing is written for a tool the server cannot dispatch, so the step is retriable once the tool is registered.

ToolRegistryUnavailable(String)

A server-performed tool step was requested but no tool registry is wired on this server (the host injected none). HTTP 503. The mirror of ModelExecutorUnavailable: no intent is written, so the run stays drivable once a registry is present.

ToolExecution(String)

The dispatch of a tool-step’s tool failed. HTTP 502. No completion is recorded, so the write-ahead intent is left dangling (the legal crash story) and the run stays drivable-or-reconcilable per the tool’s effect.

InvalidGraph

A submitted graph document failed strict validation. HTTP 400. Carries the complete, node/edge-precise error list as evidence, because a graph is a control document validated all at once (collect-all, no short-circuit), so an author sees every mistake in one response.

Fields

message: String

The human sentence.

errors: Value

The full list of structured validation errors, each naming the node or edge at fault.

UnknownGraph(String)

No graph is stored under the given hash. HTTP 404.

NotAGraphRun(String)

A graph-only endpoint (the per-run graph projection) was asked for a run whose log is not a graph run (an ordinary agent run has no GraphRunStarted head). HTTP 409.

InvalidForkNode(String)

A fork was requested from a node the origin never entered (it is not in the graph, or the walk routed past it). A fork point must be a node boundary the run reached. HTTP 409.

OriginNeedsReconciliation

A fork was requested of an origin parked at a dangling write (status NeedsReconciliation): the origin must be resolved first, since forking past an unsettled write would carry that ambiguity into the child. HTTP 409. Carries the origin’s recorded write intent as evidence, mirroring NeedsReconciliation.

Fields

message: String

The human sentence.

intent: Value

The origin’s recorded dangling write intent (the same shape a resume reconciliation refusal carries).

WriteReplayHazard

A fork would re-walk a segment containing recorded Effect::Write intents the operator has not acknowledged. HTTP 409. Carries the exact writes that would re-fire as evidence, mirroring NeedsReconciliation’s use of details: the refuse-then-record differentiator in one response the operator can read and then acknowledge.

Fields

message: String

The human sentence.

writes: Value

The unacknowledged writes the fork’s re-walked segment would re-execute, each { seq, tool, input, idempotency_key, recorded_at }.

NeedsReconciliation

A run needs human reconciliation and cannot be driven automatically. Carries the recorded write intent as evidence. HTTP 409.

Fields

message: String

The human sentence.

intent: Value

The recorded intent (tool, input, effect, idempotency key, seq, recorded time), so the caller sees exactly what to reconcile.

Internal(String)

An unexpected internal failure (a store read, an agent build). HTTP 500. The message is safe to surface: it names the layer, not a secret.

Trait Implementations

impl Debug for ApiError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl IntoResponse for ApiError

fn into_response(self) -> Response

Create a response.