Error Handling

The Reducto Python SDK raises specific exceptions for different error conditions. This guide covers all exception types and how to handle them.

Exception Hierarchy

reducto.ReductoError (base exception)
└── reducto.APIError
    ├── reducto.APIConnectionError (connection errors)
    │   └── reducto.APITimeoutError (timeout errors)
    └── reducto.APIStatusError (HTTP errors)
        ├── reducto.BadRequestError (400)
        ├── reducto.AuthenticationError (401)
        ├── reducto.PermissionDeniedError (403)
        ├── reducto.NotFoundError (404)
        ├── reducto.ConflictError (409)
        ├── reducto.UnprocessableEntityError (422)
        ├── reducto.RateLimitError (429)
        └── reducto.InternalServerError (>=500)

Common Exceptions

APIConnectionError

Raised when the SDK is unable to connect to the API (network issues, timeouts):

from reducto import Reducto
import reducto

try:
    result = client.parse.run(input=upload.file_id)
except reducto.APIConnectionError as e:
    print(f"Connection failed: {e}")
    print(e.__cause__)  # underlying exception, likely raised within httpx

AuthenticationError

Raised when API key is missing or invalid (401):

from reducto import Reducto
import reducto

try:
    client = Reducto(api_key="invalid_key")
    result = client.parse.run(input=upload.file_id)
except reducto.AuthenticationError as e:
    print(f"Authentication failed: {e}")
    print("Check your API key in Studio")

RateLimitError

Raised when rate limit is exceeded (429):

from reducto import Reducto
import reducto
import time

try:
    result = client.parse.run(input=upload.file_id)
except reducto.RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
    # The SDK automatically retries rate limit errors
    # But you can also handle it manually
    time.sleep(1)
    # Retry the request

APIStatusError

Base class for all HTTP status errors. Contains status_code and response properties:

from reducto import Reducto
import reducto

try:
    result = client.parse.run(input=upload.file_id)
except reducto.APIStatusError as e:
    print(f"API error: {e.status_code}")
    print(f"Response: {e.response}")

APITimeoutError

Raised when a request times out:

from reducto import Reducto
import reducto

try:
    result = client.parse.run(input=upload.file_id)
except reducto.APITimeoutError as e:
    print(f"Request timed out: {e}")
    print("Consider using async methods for long-running operations")

Error Code Reference

Status Code	Error Type	Description
400	BadRequestError	Invalid request parameters
401	AuthenticationError	Missing or invalid API key
403	PermissionDeniedError	Insufficient permissions
404	NotFoundError	Resource not found
409	ConflictError	Request conflicts with current state
422	UnprocessableEntityError	Request validation failed
429	RateLimitError	Rate limit exceeded
>=500	InternalServerError	Server error
N/A	APIConnectionError	Network/connection error
N/A	APITimeoutError	Request timed out

Generic Error Handling

Handle all errors with a generic catch:

from reducto import Reducto
import reducto

try:
    result = client.parse.run(input=upload.file_id)
except reducto.APIError as e:
    print(f"Reducto API error: {e}")
    # Log error, notify user, etc.
except Exception as e:
    print(f"Unexpected error: {e}")

Error Response Details

API errors include detailed information:

from reducto import Reducto
import reducto

try:
    result = client.parse.run(input=upload.file_id)
except reducto.APIStatusError as e:
    print(f"Status code: {e.status_code}")
    print(f"Response: {e.response}")
    # Access response body if needed
    if hasattr(e.response, 'text'):
        print(f"Response body: {e.response.text}")

Retry Logic

The SDK automatically retries certain errors by default (2 times with exponential backoff):

Connection errors (network issues)
408 Request Timeout
409 Conflict
429 Rate Limit
=500 Internal Server errors

You can configure retry behavior:

from reducto import Reducto

# Configure the default for all requests
client = Reducto(
    max_retries=0,  # Disable retries (default is 2)
)

# Or configure per-request
client.with_options(max_retries=5).parse.run(
    input=upload.file_id
)

Manual Retry Logic

For more control, implement your own retry logic:

import time
from reducto import Reducto
import reducto

def parse_with_retry(client, upload, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.parse.run(input=upload.file_id)
        except (reducto.RateLimitError, reducto.InternalServerError) as e:
            if attempt == max_retries - 1:
                raise
            
            wait_time = 2 ** attempt  # Exponential backoff
            print(f"Retrying in {wait_time} seconds...")
            time.sleep(wait_time)
    
    raise Exception("Max retries exceeded")

result = parse_with_retry(client, upload)

Timeout Handling

Configure timeouts for requests:

from reducto import Reducto
import httpx
import reducto

# Configure default timeout (default is 1 hour)
client = Reducto(
    timeout=20.0,  # 20 seconds
)

# More granular control
client = Reducto(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Override per-request
try:
    result = client.with_options(timeout=5.0).parse.run(
        input=upload.file_id
    )
except reducto.APITimeoutError as e:
    print(f"Request timed out: {e}")

Note that requests that time out are retried twice by default.

Long Documents and Timeouts

For large documents like lengthy PDFs or spreadsheets with many sheets, we recommend using the async endpoint. The async endpoint lets you submit a job and poll for results without holding an open connection, which is ideal for documents that take longer to process. If you need to use the sync endpoint with a custom timeout, set max_retries=0 to disable automatic retries. Otherwise, if your request times out while the server is still processing, the SDK will retry and create additional processing jobs for the same document.

from reducto import Reducto

# If using sync with a custom timeout, disable retries
client = Reducto(timeout=300.0, max_retries=0)

Best Practices

Handle Specific Exceptions

Catch specific exception types rather than generic Exception for better error handling.

Log Errors

Log errors with context (job_id, request_id) for debugging.

Retry Transient Errors

The SDK automatically retries transient errors, but you can customize retry behavior.

Provide User Feedback

Show meaningful error messages to users, not raw exceptions.

Check Connection Errors

For APIConnectionError, check e.__cause__ to see the underlying exception.

Handle Rate Limits

Rate limit errors are automatically retried, but you can also handle them manually.

Complete Example

from pathlib import Path
from reducto import Reducto
import reducto

def parse_with_comprehensive_error_handling(client, upload):
    """Parse with comprehensive error handling."""
    try:
        result = client.parse.run(input=upload.file_id)
        return result
    except reducto.AuthenticationError as e:
        print(f"Authentication failed: {e}")
        print("Check your API key in Studio")
        raise  # Don't retry auth errors
    except reducto.RateLimitError as e:
        print(f"Rate limited: {e}")
        # SDK will automatically retry, but you can also handle manually
        raise
    except reducto.APIConnectionError as e:
        print(f"Connection failed: {e}")
        print(f"Underlying error: {e.__cause__}")
        raise
    except reducto.APITimeoutError as e:
        print(f"Request timed out: {e}")
        print("Consider using async methods or increasing timeout")
        raise
    except reducto.APIStatusError as e:
        print(f"API error {e.status_code}: {e}")
        if e.status_code >= 500:
            print("Server error - may be transient")
        raise
    except Exception as e:
        print(f"Unexpected error: {e}")
        raise

# Use the function
client = Reducto()
upload = client.upload(file=Path("document.pdf"))
result = parse_with_comprehensive_error_handling(client, upload)

Next Steps

Learn about job management for async operations
Check out the async client for concurrent processing

Get Started

Core Methods

Async & Utilities

Exception Hierarchy

Common Exceptions

APIConnectionError

AuthenticationError

RateLimitError

APIStatusError

APITimeoutError

Error Code Reference

Generic Error Handling

Error Response Details

Retry Logic

Manual Retry Logic

Timeout Handling

Long Documents and Timeouts

Best Practices

Handle Specific Exceptions

Log Errors

Retry Transient Errors

Provide User Feedback

Check Connection Errors

Handle Rate Limits

Complete Example

Next Steps

​Exception Hierarchy

​Common Exceptions

​APIConnectionError

​AuthenticationError

​RateLimitError

​APIStatusError

​APITimeoutError

​Error Code Reference

​Generic Error Handling

​Error Response Details

​Retry Logic

​Manual Retry Logic

​Timeout Handling

​Long Documents and Timeouts

​Best Practices

Handle Specific Exceptions

Log Errors

Retry Transient Errors

Provide User Feedback

Check Connection Errors

Handle Rate Limits

​Complete Example

​Next Steps

Exception Hierarchy

Common Exceptions

APIConnectionError

AuthenticationError

RateLimitError

APIStatusError

APITimeoutError

Error Code Reference

Generic Error Handling

Error Response Details

Retry Logic

Manual Retry Logic

Timeout Handling

Long Documents and Timeouts

Best Practices

Complete Example

Next Steps