Enum ApiError 

pub enum ApiError {
    Unauthorized,
    NotFound {
        code: &'static str,
        message: String,
    },
    BadRequest {
        code: &'static str,
        message: String,
    },
    Internal(String),
}

Every failure the API can report, with the JSON body clients receive.

Deviation from the design

Phase 2 design §7 specified a nested body carrying the status twice ({"error": {"code", "message", "status"}}). The body here is flat — {"error": "<code>", "message": "<text>"} — and the status is only in the HTTP status line. Rationale: the status is already authoritative on the wire and repeating it in the body is a second source of truth that can disagree with the status line. Flattening also means an agent parses one object with no branch before it can read the machine code.

error is a stable machine code drawn from a closed set (ApiError::code) and is what a client should branch on. The codes are the ones §7 enumerates; message is prose for humans and is not guaranteed to be stable across releases.

Why NotFound and BadRequest carry their own code

Both map to a single HTTP status, so the status alone cannot tell an agent what went wrong: 404 covers both “no such index” and “no such node”, and 400 covers a missing param, an unparseable param, and a bad body. The status says what kind of failure; the code says which, which is what lets a client retry sensibly without matching on prose.

Variants

Unauthorized

No Authorization header, wrong scheme, unknown key, or wrong secret.

NotFound

The request was well-formed but names something that does not exist.

Fields

code: &'static str

Stable machine code, e.g. unknown_index.

message: String

Human-readable detail.

BadRequest

The request itself is malformed (missing field, bad value).

Fields

code: &'static str

Stable machine code, e.g. missing_param.

message: String

Human-readable detail.

Internal(String)

Storage, indexing, or an unexpected internal failure.

Implementations

impl ApiError

pub fn unknown_index(id: &str) -> Self

404 unknown_index: {id} does not name a database in the data dir.

pub fn unknown_node(id: &str) -> Self

404 unknown_node: the index loaded, but the node is not in the graph.

pub fn no_path(from: &str, to: &str) -> Self

404 no_path: no typed path connects the two nodes.

Not in the §7 table, which does not cover a well-formed path query whose answer is “these two symbols are unrelated”. The CLI rejects the same case rather than returning an empty path, so 404 is preserved and given its own code instead of being folded into unknown_index or reported as an empty 200.

pub fn missing_param(name: &str) -> Self

400 missing_param: a required query parameter is absent or empty.

pub fn invalid_param(name: &str, reason: &str) -> Self

400 invalid_param: a query parameter is present but unusable.

pub fn invalid_body(reason: &str) -> Self

400 invalid_body: the request body is not the expected JSON shape.

pub fn invalid_repo_path(reason: &str) -> Self

400 invalid_repo_path: repo_path is missing or is not a directory.

pub fn internal(reason: impl Into<String>) -> Self

500 from any internal failure, carrying reason.

pub fn code(&self) -> &'static str

The stable machine code clients branch on.

pub fn body(&self) -> Value

Body as a JSON value; exposed for tests and for asserting shape.

Trait Implementations

impl Debug for ApiError

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

Formats the value using the given formatter.

impl Display for ApiError

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

Formats the value using the given formatter.

impl Error for ApiError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl IntoResponse for ApiError

fn into_response(self) -> Response

Create a response.