Enum BillingError 

#[non_exhaustive]
pub enum BillingError {
    MonetaryOverflow {
        precision: u8,
        input_value: Option<Decimal>,
    },
    PrecisionLoss {
        precision: u8,
        input_value: Decimal,
    },
    InvalidSchedule {
        reason: String,
    },
    InvalidInput {
        reason: String,
    },
    ValidationFailed {
        check: String,
        actual: String,
        expected: String,
    },
    InvalidAllocationShares {
        sum: String,
    },
    ZeroPeriod,
    LayerError {
        reason: String,
    },
    CurrencyMismatch {
        left: Currency,
        right: Currency,
    },
    Parse(ParseAmountError),
}

All errors produced by the billing engine.

This enum is #[non_exhaustive]: new variants may be added in minor releases without a semver-major bump. Always include a _ => arm when matching.

Error context

BillingError::MonetaryOverflow carries input_value: Option<Decimal> — the input that caused the overflow when known. This lets callers log the offending value:

use billing::{Amount, BillingError};
use rust_decimal::Decimal;

let huge = Decimal::from(i64::MAX / 100_000 + 1);
match Amount::<5>::checked_from_decimal(huge) {
    Ok(a)  => println!("ok: {a}"),
    Err(BillingError::MonetaryOverflow { input_value: Some(v), precision }) => {
        eprintln!("overflow: {v} does not fit in Amount<{precision}>");
    }
    Err(e) => eprintln!("other error: {e}"),
}

BillingError::InvalidInput and BillingError::InvalidSchedule carry a reason: String which accepts both &'static str literals (via .into()) and dynamic messages (format!("{}", value)).

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.

MonetaryOverflow

An arithmetic operation on an crate::Amount exceeded the i64 range.

input_value carries the original Decimal that caused the overflow when known (e.g. from crate::Amount::checked_from_decimal). It is None for internal arithmetic operations (add / sub / mul) where no single input value is solely responsible.

Fields

precision: u8

The precision P of the overflowing Amount<P>.

input_value: Option<Decimal>

The input value that caused the overflow, when known. Callers can log this to identify which amount triggered the overflow.

PrecisionLoss

A Decimal carried more non-zero fractional digits than the target crate::Amount<P> can represent.

This is not overflow: the magnitude fits, the precision does not. Amount::<5>::checked_from_decimal(dec!(0.123456)) reports it, exactly as Amount::<5>::parse("0.123456") is rejected — the two conversion paths agree by construction.

To round instead of refusing, name the rounding you want with crate::Amount::from_decimal_rounded.

Fields

precision: u8

The precision P of the target Amount<P>.

input_value: Decimal

The value that could not be represented exactly.

InvalidSchedule

A crate::RateSchedule was built or used incorrectly.

Fields

reason: String

Human-readable explanation. Accepts static literals ("msg".into()) and dynamic messages (format!(...)).

InvalidInput

A function argument was invalid.

Fields

reason: String

Human-readable explanation. Accepts static literals ("msg".into()) and dynamic messages (format!(...)).

ValidationFailed

crate::BillingDocument::assert_valid detected an arithmetic inconsistency.

The check field identifies which invariant failed. The set is stable enough to match on, and every value it can take is listed here:

Emitted by	check
crate::BillingDocument::validate totals	"net_total", "tax_total", "gross_total", "discount_total"
…VAT breakdown	"tax_breakdown", "tax_breakdown_total", "vat_breakdown_presence"
…settlement	"prepaid", "prepaid_vs_prepayment", "rounding"
…positions	"net_positions", "discount_positions", "tax_positions"
crate::BillingDocument::verify_vat_attribution	"vat_attribution", "vat_total"

Fields

check: String

Which consistency check failed.

actual: String

The value computed from positions.

expected: String

The value stored in the totals field.

InvalidAllocationShares

crate::ProportionalAllocation shares do not sum to 1.0 ± 1e-9.

Fields

sum: String

The actual sum of the provided shares.

ZeroPeriod

crate::prorate was called with total_days = 0.

LayerError

A crate::TaxLayer or crate::DiscountLayer compute call failed.

Fields

reason: String

Human-readable explanation from the layer implementation.

CurrencyMismatch

Two amounts or documents in different currencies were combined.

Produced by crate::merge_period_documents. Adding amounts across currencies is never meaningful, so the engine refuses rather than silently producing a nonsense total.

Fields

left: Currency

The currency of the left-hand / first operand.

right: Currency

The currency of the right-hand / second operand.

Parse(ParseAmountError)

An crate::Amount could not be parsed from its textual form.

Wraps ParseAmountError so that parsing composes with ? inside functions returning BillingError.

Trait Implementations

impl Clone for BillingError

fn clone(&self) -> BillingError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BillingError

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

Formats the value using the given formatter.

impl Display for BillingError

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

Formats the value using the given formatter.

impl Error for BillingError

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<!> for BillingError

Infallible → BillingError conversion needed when PricingModel::Error = Infallible.

fn from(x: !) -> BillingError

Converts to this type from the input type.

impl From<BillingError> for EngineError

fn from(source: BillingError) -> Self

Converts to this type from the input type.

impl From<ParseAmountError> for BillingError

Lets Amount::parse(..)? compose inside functions returning BillingError.

fn from(e: ParseAmountError) -> BillingError

Converts to this type from the input type.

impl PartialEq for BillingError

fn eq(&self, other: &BillingError) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for BillingError