Enum XurlError 

pub enum XurlError {
    Http(String),
    Io(String),
    InvalidMethod(String),
    Api {
        status: u16,
        body: String,
    },
    Validation(String),
    InvalidUrl(String),
    InvalidPathParam {
        name: String,
        value: String,
    },
    Internal(String),
    Json(String),
    Auth(String),
    TokenStore(String),
    EnvelopeAlreadyEmitted {
        exit_code: i32,
    },
    AuthMethodMismatch {
        endpoint: String,
        rendered_url: Option<String>,
        method: String,
        requested: Option<String>,
        supported: Vec<String>,
        available_in_app: Option<Vec<String>>,
        app: Option<String>,
        other_apps_with_creds: Option<Vec<String>>,
    },
}

Top-level error type for xurl-rs.

result_large_err would fire because the largest variant (AuthMethodMismatch) carries multiple String/Vec<String> fields. Boxing the variant would change the public construction surface; allow the lint on the enum so consumers can keep building the variant inline.

Example

use xurl::error::XurlError;
match result {
    Ok(()) => println!("ok"),
    Err(XurlError::Api { status, body }) => eprintln!("api {status}: {body}"),
    Err(XurlError::Validation(msg)) => eprintln!("validation: {msg}"),
    Err(XurlError::InvalidUrl(url)) => eprintln!("bad URL: {url}"),
    Err(other) => eprintln!("{} (kind={})", other, other.kind()),
}

Variants

Http(String)

HTTP transport / request construction error.

Io(String)

File / IO error.

InvalidMethod(String)

Invalid HTTP method supplied.

Api

API returned an HTTP error response (status >= 400).

Fields

status: u16

HTTP status code from the API response.

body: String

Raw response body (typically JSON).

Validation(String)

Non-HTTP validation or logic error (e.g., missing fields, errors-only 200 responses).

InvalidUrl(String)

Raw URL supplied with an unsupported scheme. Only http:// and https:// are accepted; file/ftp/etc are rejected before any network or filesystem activity.

InvalidPathParam

Path-parameter value contained a character that would break URL semantics (/, ?, #, or %). Surfaces real IDs that contain stray separators rather than silently encoding them.

Fields

name: String

Name of the offending {param} segment in the path template.

value: String

Caller-supplied value that failed validation.

Internal(String)

Internal invariant violated — typically a programmer error such as a path template referencing a {name} segment that the caller never supplied in path_params.

Json(String)

JSON serialization / deserialization error.

Auth(String)

Authentication error with sub-type context.

TokenStore(String)

Token store persistence / lookup error.

EnvelopeAlreadyEmitted

Sentinel: a structured envelope was already emitted by the call site.

The runner short-circuits its trailing print_error for this variant and propagates the carried exit code unchanged. Used by print_confirmation_required so the canonical envelope {"status":"error","reason":"confirmation-required",…} is the only thing the agent sees on stderr (no duplicated {"error":...,"kind":...} from the generic print_error path).

Fields

exit_code: i32

Exit code the runner should surface for this error.

AuthMethodMismatch

Auth method mismatch: the user supplied (or the auto-detect resolved) an auth method the endpoint’s matrix entry doesn’t accept.

Three shapes share the variant:

• Explicit-mismatch: requested = Some("app"|"oauth1"|"oauth2"), available_in_app = None. The user passed --auth X and X isn’t in the endpoint’s supported set.
• Empty-intersection: requested = None, available_in_app = Some([nonempty]). Auto-detect resolved a non-empty available_in_app against supported to an empty intersection: no stored credential on the active app satisfies the endpoint.
• Wrong-app: requested = None, available_in_app = Some([]), other_apps_with_creds = Some([nonempty]). The active app holds no credentials but other apps in the store do — the user likely forgot --app NAME.

app carries the active app name (when known) so the recovery hint can substitute it. rendered_url carries the substituted path (/2/users/12345/likes) for user-facing messages while endpoint stays as the spec template (/2/users/{id}/likes) for agents to pattern-match against.

The Display impl renders the same body that fills the envelope’s message field.

Fields

endpoint: String

Path template (e.g. /2/users/{id}/likes) — keyed verbatim against the spec for agent pattern matching.

rendered_url: Option<String>

Path with {param} segments substituted from path_params (e.g. /2/users/12345/likes). User-facing messages prefer this over endpoint so the recovery hint doesn’t contain literal brace placeholders. None when no substitution context was available (e.g. construction outside a real call).

method: String

HTTP method, already uppercased.

requested: Option<String>

What the user asked for. Some("app"|"oauth1"|"oauth2") in the explicit-mismatch shape; None in the empty-intersection and wrong-app shapes.

supported: Vec<String>

Auth methods the endpoint accepts, as user-facing strings.

available_in_app: Option<Vec<String>>

Auth methods the active app actually has stored. None in the explicit-mismatch shape; Some([nonempty]) in the empty- intersection shape; Some([]) in the wrong-app shape.

app: Option<String>

Active app name (e.g. "default" or "bird-prod"). None when constructed outside a context that resolved an active app.

other_apps_with_creds: Option<Vec<String>>

Names of other apps in the token store that DO hold credentials. Populated only in the wrong-app shape so agents can suggest the right --app NAME to try.

Implementations

impl XurlError

pub fn api(status: u16, body: impl Into<String>) -> Self

Create an API error with an HTTP status code and response body.

pub fn validation(body: impl Into<String>) -> Self

Create a validation error for non-HTTP error conditions.

pub fn auth(message: impl Into<String>) -> Self

Create an auth error with a descriptive message.

pub fn auth_with_cause(message: &str, cause: &dyn Display) -> Self

Create an auth error with a message and underlying cause.

pub fn token_store(message: impl Into<String>) -> Self

Create a token store error.

pub fn is_api(&self) -> bool

Returns true if this is an API error (HTTP status >= 400).

pub fn is_validation(&self) -> bool

Returns true if this is a validation error.

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

Returns a typed kebab-case identifier for this error.

The closed set is the envelope reason vocabulary that agents pattern-match on. Never returns English; never embeds state.

Variant	kind()
Auth	auth-required
TokenStore	token-store
Api { 401, .. }	auth-required
Api { 429, .. }	rate-limited
Api { 404, .. }	not-found
Api { other, .. }	network-error
Http	network-error
Io	io
Json	serialization
InvalidMethod	invalid-method
Validation	validation
InvalidUrl	invalid-url
InvalidPathParam	invalid-path-param
Internal	internal
EnvelopeAlreadyEmitted	confirmation-required
AuthMethodMismatch	auth-method-mismatch

pub fn exit_code(&self) -> i32

Returns the structured exit code for this error.

Pattern-matches on Api { status, .. } directly for HTTP errors, preserves string-scanning for Http transport errors (no structured status available), and maps Validation to EXIT_GENERAL_ERROR.

Trait Implementations

impl Debug for XurlError

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

Formats the value using the given formatter.

impl Display for XurlError

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

Formats the value using the given formatter.

impl Error for XurlError

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 From<Error> for XurlError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for XurlError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for XurlError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for XurlError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<ParseError> for XurlError

fn from(err: ParseError) -> Self

Converts to this type from the input type.