Skip to main content

Error Handling

All SDK methods return Result<T, MonkError>. The error enum provides typed variants so you can match on specific failure modes.

Error Variants

VariantDescriptionRetryable
ValidationBad input caught client-side before any requestNo
ApiStructured error returned by the Monk APIDepends
NetworkDNS, connection, or TLS failureYes
TimeoutRequest exceeded the configured deadlineYes
CircuitOpenCircuit breaker is open, server assumed downNo
BufferFullIn-memory buffer is at capacityNo
SerializationFailed to encode the request bodyNo

Matching on Errors

use monk_sdk::MonkError;

match client.ingest(event).await {
    Ok(resp) => {
        println!("accepted: {}", resp.idempotency_key);
    }
    Err(MonkError::Validation(msg)) => {
        // Fix the event and retry — the input is malformed
        eprintln!("validation error: {msg}");
    }
    Err(MonkError::Api { status, code, message, request_id, .. }) => {
        eprintln!("API error {status} [{code}]: {message} (request: {request_id})");
    }
    Err(MonkError::CircuitOpen) => {
        // The server has been failing repeatedly — back off
        eprintln!("circuit breaker is open, will retry later");
    }
    Err(MonkError::BufferFull { capacity }) => {
        // Buffer is at capacity — consider switching to BackpressureStrategy::Block
        eprintln!("buffer full ({capacity} events), event dropped");
    }
    Err(e) if e.is_retryable() => {
        // Network or timeout errors — the SDK already retried, but you may
        // want to re-enqueue or log for later
        eprintln!("transient error after retries: {e}");
    }
    Err(e) => {
        eprintln!("unrecoverable error: {e}");
    }
}

Retryable Errors

Call is_retryable() on any MonkError to check whether the error is transient:
if let Err(e) = client.ingest(event).await {
    if e.is_retryable() {
        // Network, timeout, or retryable API errors (5xx, 429)
        // The SDK already attempted retries — this means all attempts failed
    }
}
The SDK automatically retries Network, Timeout, and Api errors with 5xx or 429 status codes. If you receive a retryable error, it means all retry attempts were exhausted.

Validation

The SDK validates events client-side before making a network call:
  • event_name must be non-empty
  • Exactly one of customer_id or external_customer_id must be provided
  • Batch size must not exceed 10,000 events
// This fails immediately with MonkError::Validation, no HTTP request is made
let result = Event::builder()
    .event_name("")
    .build();

assert!(result.is_err());

API Errors

MonkError::Api includes structured fields from the server response:
FieldTypeDescription
statusu16HTTP status code
codeStringMachine-readable error code (e.g. UNAUTHORIZED)
messageStringHuman-readable error description
request_idStringUnique request ID for debugging with Monk support
retryableboolWhether this error is retryable