Enum PdfServiceError 

pub enum PdfServiceError {
    InvalidUrl(String),
    EmptyHtml,
    PoolLockFailed(String),
    BrowserUnavailable(String),
    TabCreationFailed(String),
    NavigationFailed(String),
    NavigationTimeout(String),
    PdfGenerationFailed(String),
    Timeout(String),
    PoolShuttingDown,
    Internal(String),
}

Errors that can occur during PDF generation.

Each variant maps to a specific HTTP status code and error code for consistent API responses. Use status_code() and error_code() to build HTTP responses.

HTTP Status Code Mapping

Error Type	HTTP Status	Error Code
InvalidUrl	400 Bad Request	INVALID_URL
EmptyHtml	400 Bad Request	EMPTY_HTML
PoolLockFailed	500 Internal Server Error	POOL_LOCK_FAILED
BrowserUnavailable	503 Service Unavailable	BROWSER_UNAVAILABLE
TabCreationFailed	500 Internal Server Error	TAB_CREATION_FAILED
NavigationFailed	502 Bad Gateway	NAVIGATION_FAILED
NavigationTimeout	504 Gateway Timeout	NAVIGATION_TIMEOUT
PdfGenerationFailed	502 Bad Gateway	PDF_GENERATION_FAILED
Timeout	504 Gateway Timeout	TIMEOUT
PoolShuttingDown	503 Service Unavailable	POOL_SHUTTING_DOWN
Internal	500 Internal Server Error	INTERNAL_ERROR

Error Categories

Client Errors (4xx)

These indicate problems with the request that the client can fix:

• InvalidUrl - Malformed or missing URL
• EmptyHtml - Empty HTML content

Server Errors (5xx)

These indicate problems on the server side:

• PoolLockFailed - Internal synchronization issue
• TabCreationFailed - Browser tab creation failed
• Internal - Unexpected internal error

Upstream Errors (502/504)

These indicate problems with the target URL or browser:

• NavigationFailed - Failed to load the URL
• NavigationTimeout - URL took too long to load
• PdfGenerationFailed - Browser failed to generate PDF
• Timeout - Overall operation timeout

Availability Errors (503)

These indicate the service is temporarily unavailable:

• BrowserUnavailable - No browsers available in pool
• PoolShuttingDown - Service is shutting down

Examples

Error Handling

use html2pdf_api::service::{PdfServiceError, ErrorResponse};

fn handle_result(result: Result<Vec<u8>, PdfServiceError>) -> (u16, String) {
    match result {
        Ok(pdf) => (200, format!("Generated {} bytes", pdf.len())),
        Err(e) => {
            let status = e.status_code();
            let response = ErrorResponse::from(&e);
            (status, serde_json::to_string(&response).unwrap())
        }
    }
}

Retry Logic

use html2pdf_api::service::PdfServiceError;

fn should_retry(error: &PdfServiceError) -> bool {
    match error {
        // Transient errors - worth retrying
        PdfServiceError::BrowserUnavailable(_) => true,
        PdfServiceError::NavigationTimeout(_) => true,
        PdfServiceError::Timeout(_) => true,
         
        // Client errors - don't retry
        PdfServiceError::InvalidUrl(_) => false,
        PdfServiceError::EmptyHtml => false,
         
        // Server errors - maybe retry with backoff
        PdfServiceError::PoolLockFailed(_) => true,
         
        // Fatal errors - don't retry
        PdfServiceError::PoolShuttingDown => false,
         
        _ => false,
    }
}

Variants

InvalidUrl(String)

The provided URL is invalid or malformed.

Causes

• Empty URL string
• Missing URL scheme (e.g., example.com instead of https://example.com)
• Invalid URL format

Resolution

Provide a valid HTTP or HTTPS URL with proper formatting.

Example Response

{
    "error": "Invalid URL: relative URL without a base",
    "code": "INVALID_URL"
}

EmptyHtml

The HTML content is empty or contains only whitespace.

Causes

• Empty html field in request
• HTML field contains only whitespace

Resolution

Provide non-empty HTML content.

Example Response

{
    "error": "HTML content is required",
    "code": "EMPTY_HTML"
}

PoolLockFailed(String)

Failed to acquire the browser pool lock.

This is an internal error indicating a synchronization problem, typically caused by a poisoned mutex (previous panic while holding lock).

Causes

• Mutex was poisoned by a previous panic
• Deadlock condition (should not happen with correct implementation)

Resolution

This is a server-side issue. Restarting the service may help. Check logs for previous panic messages.

BrowserUnavailable(String)

No browser is available in the pool.

All browsers are currently in use and the pool is at maximum capacity.

Causes

• High request volume exceeding pool capacity
• Slow PDF generation causing browser exhaustion
• Browsers failing health checks faster than replacement

Resolution

• Retry after a short delay
• Increase max_pool_size configuration
• Reduce waitsecs to speed up PDF generation

TabCreationFailed(String)

Failed to create a new browser tab.

The browser instance is available but couldn’t create a new tab.

Causes

• Browser process is unresponsive
• System resource exhaustion (file descriptors, memory)
• Browser crashed

Resolution

The pool should automatically replace unhealthy browsers. If persistent, check system resources and browser logs.

NavigationFailed(String)

Failed to navigate to the specified URL.

The browser couldn’t load the target URL.

Causes

• URL doesn’t exist (404)
• Server error at target URL (5xx)
• SSL/TLS certificate issues
• Network connectivity problems
• Target server refusing connections

Resolution

• Verify the URL is accessible
• Check if the target server is running
• Verify SSL certificates if using HTTPS

NavigationTimeout(String)

Navigation to the URL timed out.

The browser started loading the URL but didn’t complete within the allowed time.

Causes

• Target server is slow to respond
• Large page with many resources
• Network latency issues
• Target server overloaded

Resolution

• Check target server performance
• Increase timeout if needed (via configuration)
• Optimize the target page

PdfGenerationFailed(String)

Failed to generate PDF from the loaded page.

The page loaded successfully but PDF generation failed.

Causes

• Complex page layout that can’t be rendered
• Browser rendering issues
• Memory exhaustion during rendering
• Invalid page content

Resolution

• Simplify the page layout
• Check for rendering errors in browser console
• Ensure sufficient system memory

Timeout(String)

The overall operation timed out.

The complete PDF generation operation (including queue time, navigation, and rendering) exceeded the maximum allowed duration.

Causes

• High system load
• Very large or complex pages
• Slow target server
• Insufficient waitsecs for JavaScript completion

Resolution

• Retry the request
• Increase timeout configuration
• Reduce page complexity

PoolShuttingDown

The browser pool is shutting down.

The service is in the process of graceful shutdown and not accepting new requests.

Causes

• Service restart initiated
• Graceful shutdown in progress
• Container/pod termination

Resolution

Wait for the service to restart and retry. Do not retry immediately as the service is intentionally stopping.

Internal(String)

An unexpected internal error occurred.

Catch-all for errors that don’t fit other categories.

Causes

• Unexpected panic
• Unhandled error condition
• Bug in the application

Resolution

Check server logs for details. Report persistent issues with reproduction steps.

Implementations

impl PdfServiceError

pub fn status_code(&self) -> u16

Returns the HTTP status code for this error.

Maps each error type to an appropriate HTTP status code following REST conventions.

Status Code Categories

Range	Category	Meaning
400-499	Client Error	Request problem (client can fix)
500-599	Server Error	Server problem (client can’t fix)

Examples

use html2pdf_api::service::PdfServiceError;

let error = PdfServiceError::InvalidUrl("missing scheme".to_string());
assert_eq!(error.status_code(), 400);

let error = PdfServiceError::BrowserUnavailable("pool exhausted".to_string());
assert_eq!(error.status_code(), 503);

let error = PdfServiceError::NavigationTimeout("30s exceeded".to_string());
assert_eq!(error.status_code(), 504);

pub fn error_code(&self) -> &'static str

Returns a machine-readable error code.

These codes are stable and can be used for programmatic error handling by API clients. They are returned in the code field of error responses.

Error Codes

Code	Error Type
INVALID_URL	Invalid or malformed URL
EMPTY_HTML	Empty HTML content
POOL_LOCK_FAILED	Internal pool lock error
BROWSER_UNAVAILABLE	No browsers available
TAB_CREATION_FAILED	Failed to create browser tab
NAVIGATION_FAILED	Failed to load URL
NAVIGATION_TIMEOUT	URL load timeout
PDF_GENERATION_FAILED	Failed to generate PDF
TIMEOUT	Overall operation timeout
POOL_SHUTTING_DOWN	Service shutting down
INTERNAL_ERROR	Unexpected internal error

Examples

use html2pdf_api::service::PdfServiceError;

let error = PdfServiceError::InvalidUrl("test".to_string());
assert_eq!(error.error_code(), "INVALID_URL");

// Client-side handling
match error.error_code() {
    "INVALID_URL" | "EMPTY_HTML" => println!("Fix your request"),
    "BROWSER_UNAVAILABLE" | "TIMEOUT" => println!("Retry later"),
    _ => println!("Contact support"),
}

pub fn is_retryable(&self) -> bool

Returns true if this error is likely transient and worth retrying.

Transient errors are typically caused by temporary conditions that may resolve on their own. Client errors (4xx) are never transient as they require the client to change the request.

Retryable Errors

Error	Retryable	Reason
BrowserUnavailable	✅	Pool may free up
NavigationTimeout	✅	Network may recover
Timeout	✅	Load may decrease
PoolLockFailed	✅	Rare, may recover
InvalidUrl	❌	Client must fix
EmptyHtml	❌	Client must fix
PoolShuttingDown	❌	Intentional shutdown

Examples

use html2pdf_api::service::PdfServiceError;

let error = PdfServiceError::BrowserUnavailable("pool full".to_string());
if error.is_retryable() {
    // Wait and retry
    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
}

let error = PdfServiceError::InvalidUrl("bad url".to_string());
assert!(!error.is_retryable()); // Don't retry, fix the URL

Trait Implementations

impl Clone for PdfServiceError

fn clone(&self) -> PdfServiceError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PdfServiceError

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

Formats the value using the given formatter.

impl Display for PdfServiceError

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

Formats the value using the given formatter.

impl Error for PdfServiceError

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<&PdfServiceError> for ErrorResponse

fn from(err: &PdfServiceError) -> Self

Converts to this type from the input type.

impl From<PdfServiceError> for ErrorResponse

fn from(err: PdfServiceError) -> Self

Converts to this type from the input type.