Crate fraiseql_error 

Unified error types for FraiseQL runtime crates.

All runtime crates depend on this crate for error handling.

Two-Layer Error Design

FraiseQL uses two distinct error layers with separate responsibilities:

Layer 1 — Compile-time errors: FraiseQLError (in core_error)

Returned by schema compilation, query planning, and the CLI. These are developer-facing errors that occur before any user request is processed. Library consumers building atop the Executor API will encounter this type.

use fraiseql_error::{FraiseQLError, Result};

fn compile_schema(json: &str) -> Result<CompiledSchema> {
    // Returns FraiseQLError::Parse if the JSON is malformed,
    // FraiseQLError::Validation if the schema is semantically invalid.
    todo!()
}

FraiseQLError variants: Parse, Validation, Database, Compilation, IO, Config, Unsupported, Auth, Timeout, NotFound.

Layer 2 — Runtime errors: RuntimeError

Returned by the HTTP server and live request handlers. These map directly to HTTP status codes and are safe to return to API clients (internal details are stripped before the response is sent).

Application code using the Server API will encounter this type. Conversion from FraiseQLError to RuntimeError happens automatically inside the request-handler middleware via From<FraiseQLError> for RuntimeError.

Conversion rules

FraiseQLError → RuntimeError mapping:

• Validation, Parse → RuntimeError::Internal (HTTP 400 via handler logic)
• Database → RuntimeError::Database (HTTP 500)
• Auth → RuntimeError::Auth (HTTP 401/403)
• NotFound → RuntimeError::NotFound (HTTP 404)
• Everything else → RuntimeError::Internal (HTTP 500)

RuntimeError → HTTP mapping

RuntimeError variant	HTTP status
Auth(InsufficientPermissions)	403 Forbidden
Auth(*)	401 Unauthorized
Webhook(InvalidSignature)	401 Unauthorized
RateLimited	429 Too Many Requests
ServiceUnavailable	503 Service Unavailable
NotFound	404 Not Found
Database	500 Internal Server Error
Config / Internal	500 Internal Server Error

Security note

All variants that might leak internal details (database messages, config values, provider endpoints) return generic descriptions in the HTTP response body. Raw error details are available only in structured server logs.

See also: docs/architecture/error-hierarchy.md

Re-exports

pub use core_error::ErrorContext;

pub use core_error::FraiseQLError;

pub use core_error::Result;

pub use core_error::ValidationFieldError;

pub use graphql_error::GraphQLError;

pub use graphql_error::GraphQLErrorLocation;

Modules

core_error

Core error types for FraiseQL operations.

graphql_error

Canonical GraphQL protocol error types.

Enums

AuthError

Domain-level auth errors for HTTP response mapping.

ConfigError

Errors that occur while loading or validating FraiseQL configuration.

FileError

Errors that occur during file upload, validation, storage, or retrieval.

IntegrationError

Errors that occur when communicating with external integration services such as search engines, caches, or message queues.

NotificationError

Errors that occur during notification delivery (email, SMS, push, etc.).

ObserverError

Domain-level observer errors for RuntimeError aggregation.

RuntimeError

Unified error type wrapping all domain errors.

WebhookError

Errors that occur while receiving and validating inbound webhook requests.