Struct ApiError 

pub struct ApiError {
    pub code: String,
    pub message: String,
    pub details: Option<Value>,
}

A machine-readable JSON error body.

Serializes as:

{ "code": "NOT_FOUND", "message": "item not found" }
{ "code": "VALIDATION_ERROR", "message": "invalid input", "details": { "field": "name" } }

Use the factory methods to get a (StatusCode, Json<ApiError>) tuple, which implements [IntoResponse] and can be returned directly from Axum handlers.

Example

use axum::response::IntoResponse;
use axum_api_kit::ApiError;

async fn handler() -> impl IntoResponse {
    ApiError::not_found("item not found")
}

Fields

code: String

A short, stable, machine-readable error identifier. Use SCREAMING_SNAKE_CASE.

message: String

A human-readable description of the error.

details: Option<Value>

Optional structured details (field-level validation errors, etc.).

Implementations

impl ApiError

pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self

Construct a bare ApiError without a bundled status code.

Prefer the factory methods (not_found, etc.) when returning responses directly from handlers.

pub fn with_details(self, details: Value) -> Self

Attach structured details to this error.

pub fn bad_request( code: impl Into<String>, message: impl Into<String>, ) -> (StatusCode, Json<Self>)

400 Bad Request with the provided code and message.

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

401 Unauthorized - code defaults to "AUTH_REQUIRED".

pub fn forbidden(message: impl Into<String>) -> (StatusCode, Json<Self>)

403 Forbidden - code defaults to "FORBIDDEN".

pub fn not_found(message: impl Into<String>) -> (StatusCode, Json<Self>)

404 Not Found - code defaults to "NOT_FOUND".

pub fn conflict(message: impl Into<String>) -> (StatusCode, Json<Self>)

409 Conflict - code defaults to "CONFLICT".

pub fn unprocessable(message: impl Into<String>) -> (StatusCode, Json<Self>)

422 Unprocessable Entity - code defaults to "VALIDATION_ERROR".

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

500 Internal Server Error - code defaults to "INTERNAL_ERROR".

pub fn db_error() -> (StatusCode, Json<Self>)

500 Internal Server Error for database failures - code is "DB_ERROR".

pub fn too_many_requests(message: impl Into<String>) -> (StatusCode, Json<Self>)

429 Too Many Requests - code defaults to "RATE_LIMITED".

pub fn service_unavailable( message: impl Into<String>, ) -> (StatusCode, Json<Self>)

503 Service Unavailable - code defaults to "SERVICE_UNAVAILABLE".

pub fn not_implemented(message: impl Into<String>) -> (StatusCode, Json<Self>)

501 Not Implemented - code defaults to "NOT_IMPLEMENTED".

pub fn with_source(self, source: &str) -> Self

Attach a source error message to this error.

Stores the source in the details field under the "source" key. Can be chained with other builder methods.

Example

use axum_api_kit::ApiError;

let err = ApiError::new("NOT_FOUND", "user not found")
    .with_source("SELECT * FROM users WHERE id = ?")
    .with_details(serde_json::json!({ "user_id": 42 }));

Trait Implementations

impl Clone for ApiError

fn clone(&self) -> ApiError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ComposeSchema for ApiError

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

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, f: &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 From<Error> for ApiError

Convert std::io::Error to ApiError with HTTP 500.

Maps std::io::Error to ApiError::internal() with the error message. Enables using the ? operator in handlers:

async fn handler() -> impl IntoResponse {
    let content = std::fs::read_to_string("/data.txt")?;  // auto-converts to ApiError
    Ok((StatusCode::OK, content))
}

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for ApiError

Convert serde_json::Error to ApiError with HTTP 500.

Maps JSON errors to ApiError::internal() with the error message.

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for ApiError

Available on crate feature sqlx only.

Convert sqlx::Error to an ApiError with a semantically appropriate HTTP status.

Requires the sqlx feature flag.

sqlx::Error variant	code	HTTP
RowNotFound	NOT_FOUND	404
Database (unique/FK violation)	CONFLICT	409
Database (check violation)	VALIDATION_ERROR	422
Database (other)	DB_ERROR	500
PoolTimedOut / PoolClosed / WorkerCrashed	SERVICE_UNAVAILABLE	503
everything else	DB_ERROR	500

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<ValidationErrors> for ApiError

Available on crate feature validator only.

fn from(errors: ValidationErrors) -> Self

Converts to this type from the input type.

impl Serialize for ApiError

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToSchema for ApiError

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.