errors

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 5, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package errors defines the typed failure taxonomy returned by NomLedger.

Matching

Exported sentinels identify each failure class and are matched with errors.Is: 

if errors.Is(err, ErrInvalidPrecision) {
	// handle the failure
}

Public validation failures are *ValidationError values carrying the sentinel code, operation, entry index, field, and an optional cause. Structured context is extracted with errors.As: 

var validationErr *ValidationError
if errors.As(err, &validationErr) {
	// inspect validationErr.Operation, Field, EntryIndex, and Cause
}

ValidationError.Unwrap exposes both Code and Cause, so errors.Is can match either one when both are present. In particular, ErrRateProvider covers cancellation or deadline expiry before any validation/provider work (including same-currency transactions), cancellation during a provider call, and provider errors. When cancellation and a provider error occur together, errors.Is matches both ErrRateProvider and context.Canceled; errors.As can still recover the original provider error type.

Retryability

Retryable means the caller can retry without changing the input, for example after a transient provider failure or with a fresh context. Non-retryable errors require changing the input, configuration, or caller usage.

Sentinels 

| Sentinel | Message | Returned when | Retryable |
|---|---|---|---|
| ErrZeroSumViolation | transaction does not sum to zero | Build sees functional amounts whose exact sum is non-zero. | No |
| ErrPeriodClosed | effective date falls in closed period | A non-adjusting transaction has an effective date at or before ClosedDate. A zero ClosedDate disables the check. | No |
| ErrRateDeviation | exchange rate exceeds tolerance | Provider and entry rates differ by more than RateTolerance. | No |
| ErrRateProvider | rate provider error | Context cancellation or deadline expiry before any validation/provider work (including same-currency transactions), cancellation during a provider call, or a provider call returns an error. | Yes |
| ErrInvalidPrecision | amount exceeds currency precision | An Entry or Money amount has more decimal places than the currency's minor units. | No |
| ErrCurrencyMismatch | entry functional currency does not match ledger | An entry's functional currency differs from the ledger's, or Money arithmetic mixes currencies. | No |
| ErrEmptyTransaction | transaction must contain at least one entry | Build receives zero entries. | No |
| ErrZeroAmount | transaction amount must be non-zero | NewEntry receives a zero transaction amount. | No |
| ErrFunctionalAmountZero | functional amount rounds to zero | A non-zero transaction amount rounds to zero in the functional currency. | No |
| ErrInvalidEntry | invalid entry | Entry.Validate sees a zero-value or internally inconsistent entry, or Build's entry check fails. | No |
| ErrNilRateProvider | rate provider must not be nil | NewLedger receives a nil provider, or a rate lookup is attempted without one. | No |
| ErrInvalidTransactionID | invalid transaction ID | Build receives an empty, over-255-byte, or control-character transaction ID. | No |
| ErrInvalidEffectiveDate | invalid effective date | Build receives the zero time as the effective date. | No |
| ErrInvalidMetadata | invalid metadata | Build receives a metadata key that is empty, over 64 bytes, or contains a control character. | No |
| ErrInvalidAccountID | invalid account ID | NewAccount, NewEntry, or their Validate methods receive an invalid account ID. | No |
| ErrInvalidAccountType | invalid account type | NewAccount or Account.Validate receives an unsupported account type. | No |
| ErrInvalidMeasurementCategory | invalid measurement category | NewAccount or Account.Validate receives an unsupported measurement category. | No |
| ErrInvalidExchangeRate | exchange rate must be strictly positive | An entry or provider rate is zero or negative, or a same-currency entry rate is not exactly one. | No |
| ErrInvalidConfiguration | invalid ledger configuration | LedgerConfig has an invalid functional currency or a negative tolerance. | No |
| ErrUnknownCurrency | unknown or unsupported currency code | A well-formed code is absent from the active ISO 4217 registry. | No |
| ErrInvalidCurrencyCode | currency code must be exactly three ASCII letters | A currency code is not exactly three ASCII letters. | No |
| ErrCurrencyNotRatable | currency has no defined minor units | A currency with N.A. minor units is used where ratability is required. | No |
| ErrInvalidRoundingMode | invalid rounding mode | Round receives an unknown RoundingMode. | No |
| ErrInexactRounding | rounding would change the value | RoundUnnecessary would change the numeric amount. | No |
| ErrBuilderFinalized | builder is already finalized | Build is called again after a successful build finalized the builder. | No |

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrZeroSumViolation indicates the transaction entries do not sum to zero.
	ErrZeroSumViolation = errors.New("transaction does not sum to zero")

	// ErrPeriodClosed indicates the effective date falls in a closed period,
	// and the event is not marked as an adjusting event.
	ErrPeriodClosed = errors.New("effective date falls in closed period")

	// ErrRateDeviation indicates the exchange rate provided exceeds the
	// allowable tolerance compared to the RateProvider.
	ErrRateDeviation = errors.New("exchange rate exceeds tolerance")

	// ErrRateProvider indicates a rate provider failure or context cancellation
	// while obtaining exchange rates.
	ErrRateProvider = errors.New("rate provider error")

	// ErrInvalidPrecision indicates an amount exceeds the ISO 4217 precision
	// defined for that currency.
	ErrInvalidPrecision = errors.New("amount exceeds currency precision")

	// ErrCurrencyMismatch indicates an entry's functional currency does not
	// match the ledger's configured functional currency.
	ErrCurrencyMismatch = errors.New("entry functional currency does not match ledger")

	// ErrEmptyTransaction indicates the transaction contains no entries.
	// Zero-entry transactions are strictly invalid.
	ErrEmptyTransaction = errors.New("transaction must contain at least one entry")

	// ErrZeroAmount indicates a transaction amount is zero.
	ErrZeroAmount = errors.New("transaction amount must be non-zero")

	// ErrFunctionalAmountZero indicates a non-zero transaction amount rounds to
	// zero in the functional currency.
	ErrFunctionalAmountZero = errors.New("functional amount rounds to zero")

	// ErrInvalidEntry indicates a zero-value or internally inconsistent entry.
	ErrInvalidEntry = errors.New("invalid entry")

	// ErrNilRateProvider indicates a nil rate provider was supplied or a rate
	// lookup was attempted without one.
	ErrNilRateProvider = errors.New("rate provider must not be nil")

	// ErrInvalidTransactionID indicates the transaction ID is empty, too long,
	// or contains a control character.
	ErrInvalidTransactionID = errors.New("invalid transaction ID")

	// ErrInvalidEffectiveDate indicates the effective date is the zero time.
	ErrInvalidEffectiveDate = errors.New("invalid effective date")

	// ErrInvalidMetadata indicates a metadata key is empty, too long, or
	// contains a control character.
	ErrInvalidMetadata = errors.New("invalid metadata")

	// ErrInvalidAccountID indicates the account ID is empty, too long, or
	// contains a control character.
	ErrInvalidAccountID = errors.New("invalid account ID")

	// ErrInvalidAccountType indicates the account type is not one of the
	// supported reporting classifications.
	ErrInvalidAccountType = errors.New("invalid account type")

	// ErrInvalidMeasurementCategory indicates the measurement category is not
	// one of the supported IFRS 9 tags.
	ErrInvalidMeasurementCategory = errors.New("invalid measurement category")

	// ErrInvalidExchangeRate indicates a logic error in the exchange rate.
	// Both entry-provided rates and provider-returned rates must be strictly positive.
	// Zero or negative rates are invalid.
	ErrInvalidExchangeRate = errors.New("exchange rate must be strictly positive")

	// ErrInvalidConfiguration indicates the LedgerConfig is malformed (e.g. negative tolerance).
	ErrInvalidConfiguration = errors.New("invalid ledger configuration")

	// ErrUnknownCurrency indicates the currency code is well-formed but not
	// present in the active ISO 4217 registry.
	ErrUnknownCurrency = errors.New("unknown or unsupported currency code")

	// ErrInvalidCurrencyCode indicates the currency code is not exactly three
	// ASCII letters.
	ErrInvalidCurrencyCode = errors.New("currency code must be exactly three ASCII letters")

	// ErrCurrencyNotRatable indicates the currency has no defined minor units
	// and therefore cannot be used for monetary amounts.
	ErrCurrencyNotRatable = errors.New("currency has no defined minor units")

	// ErrInvalidRoundingMode indicates the requested rounding mode is unknown.
	ErrInvalidRoundingMode = errors.New("invalid rounding mode")

	// ErrInexactRounding indicates an unnecessary-rounding request would change
	// the numeric value.
	ErrInexactRounding = errors.New("rounding would change the value")

	// ErrBuilderFinalized indicates Build was called again after a successful
	// build finalized the builder.
	ErrBuilderFinalized = errors.New("builder is already finalized")
)

Typed Error Taxonomy as defined in the Technical Design.

Functions

This section is empty.

Types

type ValidationError 

type ValidationError struct {
	// Code is the sentinel error that identifies the failure class.
	Code error
	// Operation is the public operation that rejected the input.
	Operation string
	// EntryIndex is -1 for transaction-level failures or the zero-based entry
	// index for entry-level failures.
	EntryIndex int
	// Field is the input field associated with the failure, when known.
	Field string
	// Cause is the underlying error, when one exists.
	Cause error
}

ValidationError describes a validation failure and the context in which it occurred.

func NewEntryValidationError 

func NewEntryValidationError(code error, operation string, entryIndex int, field string, cause error) *ValidationError

NewEntryValidationError returns an entry-level ValidationError with the supplied zero-based entry index.

func NewValidationError 

func NewValidationError(code error, operation, field string, cause error) *ValidationError

NewValidationError returns a transaction-level ValidationError. Its EntryIndex is -1.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Error returns a deterministic, readable description of the validation failure. It includes the operation, entry index, field, code, and cause when those details are present.

func (*ValidationError) Unwrap 

func (e *ValidationError) Unwrap() error

Unwrap exposes both the sentinel code and the cause so errors.Is and errors.As can inspect either one.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.