Exceptions Reference

TimeSeed defines a dedicated hierarchy of custom exception classes derived from the base TimeSeedError class, making error handling clean and granular.

Exception Hierarchy

TimeSeedError
 ├── ConfigurationError
 │    └── BitAllocationError
 ├── ClockError
 │    └── ClockBackwardError
 ├── SequenceOverflowError
 ├── MachineIdError
 ├── DatacenterIdError
 ├── DecodingError
 ├── FormatError
 └── ValidationError

Class Definitions

TimeSeedError

The base exception class for all errors raised by the TimeSeed library.

ConfigurationError

Raised when the generator configuration is invalid (e.g., negative machine ID overrides, invalid starting epochs, etc.).

BitAllocationError

Raised when the custom bit allocation configuration fails post-initialization validation (e.g., total bits exceed 128, sequence bits are too small, etc.).

ClockError

Raised when clock-related issues are encountered.

ClockBackwardError

Raised when the system clock is adjusted backwards by more than the configured clock_backward_tolerance_ms limit.

SequenceOverflowError

Raised when more identifiers are requested in a single millisecond than the sequence bits allocation allows (only raised if sequence_overflow_wait is configured to False).

MachineIdError

Raised when the resolved or provided Machine ID is out of range for the configured bit size.

DatacenterIdError

Raised when the resolved or provided Datacenter ID is out of range for the configured bit size.

DecodingError

Raised when decoding an ID fails because it is malformed or invalid.

FormatError

Raised when conversion between representation formats (hex, base62, base32, binary, integer) fails.

ValidationError

Raised when an ID fails integrity or structure checks.