Enum FraiseQLError 

#[non_exhaustive]
pub enum FraiseQLError {
    Parse {
        message: String,
        location: String,
    },
    Validation {
        message: String,
        path: Option<String>,
    },
    UnknownField {
        field: String,
        type_name: String,
    },
    UnknownType {
        type_name: String,
    },
    Database {
        message: String,
        sql_state: Option<String>,
    },
    ConnectionPool {
        message: String,
    },
    Timeout {
        timeout_ms: u64,
        query: Option<String>,
    },
    Cancelled {
        query_id: String,
        reason: String,
    },
    Authorization {
        message: String,
        action: Option<String>,
        resource: Option<String>,
    },
    Authentication {
        message: String,
    },
    RateLimited {
        message: String,
        retry_after_secs: u64,
    },
    NotFound {
        resource_type: String,
        identifier: String,
    },
    Conflict {
        message: String,
    },
    Configuration {
        message: String,
    },
    Unsupported {
        message: String,
    },
    Internal {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
}

Main error type for FraiseQL operations.

All errors in the core library are converted to this type. Language bindings convert this to their native error types.

Error Categories

Errors are organized by domain:

GraphQL Errors

• Parse — Malformed GraphQL syntax
• Validation — Schema validation failures
• UnknownField — Field doesn’t exist on type
• UnknownType — Type doesn’t exist in schema

Database Errors

• Database — PostgreSQL/MySQL/SQLite errors (includes SQL state code)
• ConnectionPool — Connection pool exhausted or unavailable
• Timeout — Query exceeded configured timeout
• Cancelled — Query was cancelled by caller

Authorization/Security Errors

• Authorization — User lacks permission for operation
• Authentication — Invalid/expired JWT token
• RateLimited — Too many requests (includes retry-after)

Resource Errors

• NotFound — Resource doesn’t exist (404)
• Conflict — Operation would violate constraints (409)

Configuration Errors

• Configuration — Invalid setup/configuration
• Unsupported — Operation not supported by current database backend

Internal Errors

• Internal — Unexpected internal failures

Stability

This enum is marked #[non_exhaustive] to allow adding new error variants in future minor versions without breaking backward compatibility.

External match expressions must include a wildcard _ arm:

use fraiseql_error::FraiseQLError;

fn describe(e: &FraiseQLError) -> &'static str {
    match e {
        FraiseQLError::Parse { .. } => "parse error",
        FraiseQLError::Validation { .. } => "validation error",
        _ => "other error", // required: FraiseQLError is #[non_exhaustive]
    }
}

The following would not compile (missing wildcard arm):

use fraiseql_error::FraiseQLError;

fn describe(e: &FraiseQLError) -> &'static str {
    match e {
        FraiseQLError::Parse { .. } => "parse",
        FraiseQLError::Validation { .. } => "validation",
        FraiseQLError::Database { .. } => "database",
        FraiseQLError::Network { .. } => "network",
        FraiseQLError::Authorization { .. } => "authorization",
        FraiseQLError::NotFound { .. } => "not found",
        FraiseQLError::Conflict { .. } => "conflict",
        FraiseQLError::Configuration { .. } => "configuration",
        FraiseQLError::Unsupported { .. } => "unsupported",
        FraiseQLError::Internal { .. } => "internal",
        FraiseQLError::UnknownField { .. } => "unknown field",
        FraiseQLError::UnknownType { .. } => "unknown type",
        FraiseQLError::FieldExclusion { .. } => "field exclusion",
        FraiseQLError::TypeMismatch { .. } => "type mismatch",
        FraiseQLError::RateLimitExceeded { .. } => "rate limit",
        FraiseQLError::Forbidden { .. } => "forbidden",
    }
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Parse

GraphQL parsing error.

Fields

message: String

Error message describing the parse failure.

location: String

Location in the query where the error occurred.

Validation

GraphQL validation error.

Fields

message: String

Error message describing the validation failure.

path: Option<String>

Path to the field with the error (e.g., “user.posts.0.title”).

UnknownField

Unknown field error.

Fields

field: String

The field name that was not found.

type_name: String

The type on which the field was queried.

UnknownType

Unknown type error.

Fields

type_name: String

The type name that was not found.

Database

Database operation error.

Fields

message: String

Error message from the database.

sql_state: Option<String>

SQL state code if available (e.g., “23505” for unique violation).

ConnectionPool

Connection pool error.

Fields

message: String

Error message.

Timeout

Query timeout error.

Fields

timeout_ms: u64

Timeout duration in milliseconds.

query: Option<String>

The query that timed out (truncated if too long).

Cancelled

Query cancellation error.

Fields

query_id: String

Query identifier for tracking/logging.

reason: String

Reason for cancellation.

Authorization

Authorization error.

Fields

message: String

Error message.

action: Option<String>

The action that was denied.

resource: Option<String>

The resource that was being accessed.

Authentication

Authentication error.

Fields

message: String

Error message.

RateLimited

Rate limiting error.

Fields

message: String

Error message.

retry_after_secs: u64

Number of seconds to wait before retrying.

NotFound

Resource not found error.

Fields

resource_type: String

Type of resource (e.g., “User”, “Post”).

identifier: String

Identifier that was looked up.

Conflict

Conflict error.

Fields

message: String

Error message.

Configuration

Configuration error.

Fields

message: String

Error message.

Unsupported

Unsupported operation error.

Fields

message: String

Error message describing what is not supported.

Internal

Internal error.

Fields

message: String

Error message.

source: Option<Box<dyn Error + Send + Sync>>

Optional source error for debugging.

Implementations

impl FraiseQLError

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

Create a parse error.

pub fn parse_at(message: impl Into<String>, location: impl Into<String>) -> Self

Create a parse error with location.

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

Create a validation error.

pub fn validation_at( message: impl Into<String>, path: impl Into<String>, ) -> Self

Create a validation error with path.

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

Create a database error.

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

Create an authorization error.

pub fn not_found( resource_type: impl Into<String>, identifier: impl Into<String>, ) -> Self

Create a not found error.

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

Create a configuration error.

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

Create an internal error.

pub fn cancelled(query_id: impl Into<String>, reason: impl Into<String>) -> Self

Create a cancellation error.

pub const fn is_client_error(&self) -> bool

Check if this is a client error (4xx equivalent).

pub const fn is_server_error(&self) -> bool

Check if this is a server error (5xx equivalent).

pub const fn is_retryable(&self) -> bool

Check if this error is retryable.

pub const fn status_code(&self) -> u16

Get HTTP status code equivalent.

pub const fn error_code(&self) -> &'static str

Get error code for GraphQL response.

pub fn unknown_field_with_suggestion( field: impl Into<String>, type_name: impl Into<String>, available_fields: &[&str], ) -> Self

Create an unknown field error with helpful suggestions.

pub fn from_postgres_code(code: &str, message: impl Into<String>) -> Self

Create a database error from PostgreSQL error code.

pub fn rate_limited_with_retry(retry_after_secs: u64) -> Self

Create a rate limit error with retry information.

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

Create an authentication error with context.

Trait Implementations

impl Debug for FraiseQLError

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

Formats the value using the given formatter.

impl Display for FraiseQLError

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

Formats the value using the given formatter.

impl Error for FraiseQLError

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 FraiseQLError

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<Error> for FraiseQLError

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<VarError> for FraiseQLError

fn from(e: VarError) -> Self

Converts to this type from the input type.