Enum ApiError

pub enum ApiError {
    Configuration {
        message: String,
    },
    Network {
        message: String,
    },
    Protocol {
        message: String,
    },
    Dialog {
        message: String,
    },
    Internal {
        message: String,
    },
}

Simplified error type for API consumers

Provides high-level error categories that applications can handle appropriately without needing to understand internal dialog-core details.

Design Principles

• User-friendly: Clear, actionable error messages
• Categorized: Logical grouping for appropriate handling
• Abstracted: Hides internal implementation complexity
• Consistent: Uniform error handling across all APIs

Error Categories

Configuration Errors

Issues with setup, parameters, or invalid configurations:

• Invalid URIs or addresses
• Missing required parameters
• Incompatible configuration combinations

Network Errors

Connectivity and transport-related issues:

• Connection failures
• Transport errors
• Timeout issues

Protocol Errors

SIP protocol violations and parsing errors:

• Malformed SIP messages
• Protocol state violations
• Unsupported SIP features

Dialog Errors

Dialog state and lifecycle issues:

• Dialog not found
• Invalid dialog state transitions
• Dialog termination errors

Internal Errors

Implementation or system-level errors:

• Unexpected internal states
• System resource issues
• Programming errors

Variants

Configuration

Configuration error

Indicates an issue with configuration parameters, setup, or initialization. These errors typically require user intervention to fix the configuration.

Common Causes

• Invalid URI formats
• Missing required parameters
• Incompatible configuration options
• Invalid network addresses

Example Response

Review and correct the configuration parameters.

Fields

message: String

Human-readable error message

Network

Network error

Indicates connectivity or transport-related issues. These errors may be transient and worth retrying.

Common Causes

• Network connectivity issues
• Server unavailable
• Connection timeouts
• Transport layer failures

Example Response

Check network connectivity and retry the operation.

Fields

message: String

Human-readable error message

Protocol

SIP protocol error

Indicates violations of the SIP protocol or parsing errors. These errors suggest malformed messages or protocol misuse.

Common Causes

• Malformed SIP messages
• Invalid SIP headers
• Protocol state violations
• Unsupported SIP extensions

Example Response

Review SIP message formatting and protocol compliance.

Fields

message: String

Human-readable error message

Dialog

Dialog error

Indicates issues with dialog state, lifecycle, or operations. These errors suggest problems with dialog management.

Common Causes

• Dialog not found
• Invalid state transitions
• Dialog already terminated
• Concurrent access issues

Example Response

Check dialog state and ensure proper lifecycle management.

Fields

message: String

Human-readable error message

Internal

Internal error

Indicates unexpected internal errors or system issues. These errors suggest bugs or system-level problems.

Common Causes

• Programming errors
• System resource exhaustion
• Unexpected internal states
• Concurrency issues

Example Response

These errors should be reported as potential bugs.

Fields

message: String

Human-readable error message

Implementations

impl ApiError

pub fn configuration(message: impl Into<String>) -> Self

Create a configuration error

pub fn network(message: impl Into<String>) -> Self

Create a network error

pub fn protocol(message: impl Into<String>) -> Self

Create a protocol error

pub fn dialog(message: impl Into<String>) -> Self

Create a dialog error

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

Create an internal error

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 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<AddrParseError> for ApiError

Convert from address parsing errors to ApiError

fn from(error: AddrParseError) -> Self

Converts to this type from the input type.

impl From<DialogError> for ApiError

Convert from internal DialogError to public ApiError

This conversion abstracts internal error details and provides user-friendly error categories for API consumers.

fn from(error: DialogError) -> Self

Converts to this type from the input type.

impl From<Error> for ApiError

Convert from standard io::Error to ApiError

fn from(error: Error) -> Self

Converts to this type from the input type.

impl From<Error> for ApiError

Convert from serialization errors to ApiError

fn from(error: Error) -> Self

Converts to this type from the input type.

impl From<InvalidUri> for ApiError

Convert from URI parsing errors to ApiError

fn from(error: InvalidUri) -> Self

Converts to this type from the input type.