Error Handling Guide

Exception Hierarchy

SteadfastException (base)
├── AuthenticationError
├── ValidationError
├── NotFoundError
├── APIError
├── NetworkError
└── ConfigurationError

Exception Types

SteadfastException

Base exception for all Steadfast SDK errors.

from steadfast import SteadfastException

try:
    # SDK operation
    pass
except SteadfastException as e:
    print(f"Steadfast error: {e}")

AuthenticationError

Raised when authentication fails (HTTP 401).

from steadfast import AuthenticationError

try:
    order = client.orders.create(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    # Check API key and secret key

ValidationError

Raised when input validation fails.

from steadfast import ValidationError

try:
    order = client.orders.create(
        invoice="invalid@invoice",  # Invalid characters
        recipient_name="John Smith",
        recipient_phone="01234567890",
        recipient_address="House 123, Dhaka",
        cod_amount=1060,
        delivery_type=0,
    )
except ValidationError as e:
    print(f"Validation error: {e}")
    print(f"Field: {e.field}")  # Access field name

NotFoundError

Raised when resource is not found (HTTP 404).

from steadfast import NotFoundError

try:
    status = client.tracking.get_status_by_consignment_id(999)
except NotFoundError as e:
    print(f"Order not found: {e}")

APIError

Raised for general API errors.

from steadfast import APIError

try:
    order = client.orders.create(...)
except APIError as e:
    print(f"API error: {e}")
    print(f"Status code: {e.status_code}")  # Access HTTP status code

NetworkError

Raised for network-related errors with retry information.

from steadfast import NetworkError

try:
    order = client.orders.create(...)
except NetworkError as e:
    print(f"Network error: {e}")
    if e.retry_after:
        print(f"Retry after: {e.retry_after} seconds")

ConfigurationError

Raised when SDK is not properly configured.

from steadfast import ConfigurationError

try:
    # Missing API key
    client = SteadfastClient(secret_key="secret")
except ConfigurationError as e:
    print(f"Configuration error: {e}")

Error Handling Patterns

Basic Try-Catch

from steadfast import SteadfastClient, ValidationError, APIError, NetworkError

client = SteadfastClient(api_key="key", secret_key="secret")

try:
    order = client.orders.create(
        invoice="ORD-2024-001",
        recipient_name="John Smith",
        recipient_phone="01234567890",
        recipient_address="House 123, Dhaka",
        cod_amount=1060,
        delivery_type=0,
    )
    print(f"Order created: {order.consignment_id}")
except ValidationError as e:
    print(f"Invalid input: {e}")
except APIError as e:
    print(f"API error: {e}")
except NetworkError as e:
    print(f"Network error: {e}")

Retry Logic

import time
from steadfast import SteadfastClient, NetworkError

client = SteadfastClient(api_key="key", secret_key="secret")

def create_order_with_retry(max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            order = client.orders.create(
                invoice="ORD-2024-001",
                recipient_name="John Smith",
                recipient_phone="01234567890",
                recipient_address="House 123, Dhaka",
                cod_amount=1060,
                delivery_type=0,
            )
            return order
        except NetworkError as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Retry in {wait_time} seconds...")
                time.sleep(wait_time)
            else:
                raise

order = create_order_with_retry()

Specific Error Handling

from steadfast import (
    SteadfastClient,
    ValidationError,
    NotFoundError,
    AuthenticationError,
    APIError,
    NetworkError,
)

client = SteadfastClient(api_key="key", secret_key="secret")

try:
    status = client.tracking.get_status_by_consignment_id(123)
except ValidationError as e:
    # Handle validation errors
    print(f"Invalid input: {e}")
except NotFoundError as e:
    # Handle not found
    print(f"Order not found: {e}")
except AuthenticationError as e:
    # Handle authentication
    print(f"Authentication failed: {e}")
except APIError as e:
    # Handle API errors
    print(f"API error ({e.status_code}): {e}")
except NetworkError as e:
    # Handle network errors
    print(f"Network error: {e}")

Bulk Operation Error Handling

from steadfast import SteadfastClient

client = SteadfastClient(api_key="key", secret_key="secret")

orders = [
    {
        "invoice": "ORD-2024-001",
        "recipient_name": "John Smith",
        "recipient_phone": "01234567890",
        "recipient_address": "House 123, Dhaka",
        "cod_amount": 1060,
        "delivery_type": 0,
    },
    {
        "invoice": "ORD-2024-002",
        "recipient_name": "Jane Doe",
        "recipient_phone": "01987654321",
        "recipient_address": "Apt 456, Chittagong",
        "cod_amount": 2500,
        "delivery_type": 1,
    },
]

try:
    response = client.orders.create_bulk(orders)

    successful = []
    failed = []

    for result in response.results:
        if result.status == "success":
            successful.append(result)
        else:
            failed.append(result)

    print(f"Successful: {len(successful)}")
    print(f"Failed: {len(failed)}")

    for result in failed:
        print(f"Order {result.invoice}: {result.error}")

except Exception as e:
    print(f"Bulk operation failed: {e}")

Common Error Scenarios

Invalid Credentials

from steadfast import SteadfastClient, ConfigurationError

try:
    client = SteadfastClient()  # No credentials provided
except ConfigurationError as e:
    print(f"Error: {e}")
    # Solution: Provide api_key and secret_key or set environment variables

Invalid Input

from steadfast import ValidationError

try:
    order = client.orders.create(
        invoice="invalid@invoice",  # Invalid characters
        recipient_name="John Smith",
        recipient_phone="01234567890",
        recipient_address="House 123, Dhaka",
        cod_amount=1060,
        delivery_type=0,
    )
except ValidationError as e:
    print(f"Error: {e}")
    # Solution: Use valid invoice format (alphanumeric, hyphens, underscores)

Network Timeout

from steadfast import NetworkError

try:
    order = client.orders.create(...)
except NetworkError as e:
    print(f"Error: {e}")
    # Solution: Check network connection and retry

Order Not Found

from steadfast import NotFoundError

try:
    status = client.tracking.get_status_by_consignment_id(999)
except NotFoundError as e:
    print(f"Error: {e}")
    # Solution: Verify consignment ID is correct

Best Practices

Always catch specific exceptions first, then general ones
Log errors with context for debugging
Implement retry logic for network errors
Validate input early to catch ValidationError
Handle bulk operations with partial failure support
Use environment variables for credentials
Never log sensitive data (API keys, secret keys)