Advanced Configuration

This page covers advanced configuration options for performance tuning, error handling, and special use cases. Values here map to intapp-rest-client RestClient and related types (RetryConfig, timeouts, concurrency).

Timeout Configuration

Request Timeout

Control how long to wait for API responses:

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
    connectorTimeoutSeconds=180  # 3 minutes for large operations
)
 
dc = DealCloud.from_config_object(config)

Recommended timeouts by operation type:

Operation	Recommended Timeout	Notes
Schema reads	30s	Small payloads
Data reads (< 10k rows)	60s	Default
Data reads (> 100k rows)	180s	Large datasets
File uploads	300s	Large files
Backup operations	600s	Site-wide

Retry Configuration

Exponential Backoff

The SDK uses exponential backoff for transient failures:

config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
    responseRetrySettings={
        "tooManyRequests": 10,      # Retry 429s up to 10 times
        "internalServerError": 3,    # Retry 500s up to 3 times
        "serviceUnavailable": 3,     # Retry 503s up to 3 times
        "backoffFactor": 2.0         # Delay: 2^attempt seconds
    }
)

Retry Timing

With backoffFactor=2, retry delays are:

Attempt	Delay
1	2 seconds
2	4 seconds
3	8 seconds
4	16 seconds
5	32 seconds

💡

For rate limiting (429), the SDK respects the Retry-After header if provided by the API.

Concurrency Control

Parallel Request Limits

Control concurrent API requests to avoid rate limiting:

config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
    concurrencyLimits={
        "read": 4,    # Up to 4 parallel read requests
        "delete": 2,  # Up to 2 parallel delete requests
        "create": 2   # Up to 2 parallel create/update requests
    }
)

Tuning Guidelines

Scenario	Read	Create	Delete	Notes
Default	2	2	2	Safe for all sites
High-volume reads	4-6	2	2	Schema reads are fast
Bulk imports	2	4	2	More write parallelism
Conservative	1	1	1	Lowest rate limit risk

⚠️

Higher concurrency increases throughput but may trigger rate limiting. Monitor your API usage.

Pagination Settings

Page Sizes

Optimize for your data volume:

config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
    querySettings={
        "pageSize": 1000,           # Rows per page
        "cellPaginationLimit": 9000, # Cells per page
        "deletePageSize": 10000      # Deletes per batch
    }
)

Page Size Trade-offs

Size	Memory	Requests	Best For
100	Low	Many	Small rows, memory-constrained
500	Medium	Medium	General use
1000	Higher	Fewer	Large operations (default)
5000	High	Minimal	Streaming, high-bandwidth

Error Handling Configuration

Error Handling Strategies

The SDK supports different error handling modes:

from dealcloud_sdk import DealCloud, DealCloudConfig, ErrorHandling
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# Fail on first transport error (default)
result = dc.insert_data(
    "Company",
    data,
    error_handling=ErrorHandling.FAIL_FAST
)
 
# Collect all errors, continue processing
result = dc.insert_data(
    "Company",
    data,
    error_handling=ErrorHandling.COLLECT
)
 
# Log errors, continue processing
result = dc.insert_data(
    "Company",
    data,
    error_handling=ErrorHandling.LOG
)

Mode	Behavior	Use Case
`FAIL_FAST`	Stop on first transport error	Data integrity critical
`COLLECT`	Continue, return errors	Batch processing
`LOG`	Continue, log warnings	Background jobs

Row error defaults

Set raiseOnRowErrors on DealCloudConfig so all write methods raise on row-level "Errors" unless a call passes raise_on_row_errors=False. See Error handling.

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
    raiseOnRowErrors=True,
)
dc = DealCloud.from_config_object(config)
 
# All write methods inherit strict row-error behavior unless overridden
dc.insert_data("Company", records, raise_on_row_errors=False)

Logging Configuration

Configure SDK Logging

import logging
 
# Configure logging before creating client
logging.basicConfig(level=logging.DEBUG)
 
# Or configure specific SDK logger
dc_logger = logging.getLogger("dealcloud_sdk")
dc_logger.setLevel(logging.DEBUG)
 
# Create client
from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)

Log Levels

Level	Content
`DEBUG`	All HTTP requests/responses, pagination details
`INFO`	Operation summaries, record counts
`WARNING`	Retries, non-fatal errors
`ERROR`	Failed operations, API errors

Custom Log Handler

import logging
 
# Create custom handler
handler = logging.FileHandler("dealcloud.log")
handler.setLevel(logging.INFO)
handler.setFormatter(logging.Formatter(
    "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
))
 
# Add to SDK logger
logging.getLogger("dealcloud_sdk").addHandler(handler)

Connection Pooling

The SDK manages HTTP connection pools automatically:

from dealcloud_sdk import DealCloud, DealCloudConfig
 
# Connections are reused across requests
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# All these requests share connection pool
data1 = dc.read_data("Company", output="list")
data2 = dc.read_data("Contact", output="list")
data3 = dc.read_data("Deal", output="list")

Pool Configuration

For advanced HTTP client tuning:

import httpx
 
# The SDK uses httpx under the hood
# Connection pool is configured via intapp-rest-client

Proxy Configuration

For environments requiring proxy access:

import os
 
# Set before creating client
os.environ["HTTP_PROXY"] = "http://proxy.company.com:8080"
os.environ["HTTPS_PROXY"] = "http://proxy.company.com:8080"
os.environ["NO_PROXY"] = "localhost,127.0.0.1"
 
from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)

Runtime Configuration Access

Access and modify configuration at runtime via public properties:

Read-Only Properties

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# Access current configuration
print(f"Site: {dc.site_url}")
print(f"API URL: {dc.api_url}")
print(f"Auth scope: {dc.auth_scope}")
print(f"Page size: {dc.page_size}")
print(f"Read concurrency: {dc.read_concurrency}")
 
# URL endpoints for custom API calls
print(f"Schema URL: {dc.schema_url}")
print(f"Data URL: {dc.data_url}")
print(f"Query URL: {dc.query_url}")

Mutable Properties

Some settings can be adjusted at runtime:

# Adjust retry behavior
dc.retry_status_codes[429] = 10  # More retries for rate limiting
 
# Adjust concurrency (if config-based)
if dc.concurrency_limits:
    dc.concurrency_limits.read = 8  # Increase read parallelism
 
# Adjust pagination (if config-based)
if dc.query_settings:
    dc.query_settings.pageSize = 500  # Smaller pages

Direct API Access

For custom endpoints not covered by SDK methods:

# Use the underlying REST client
response = dc.client.get(f"{dc.api_url}/custom/endpoint")
 
# Get auth headers for other libraries
headers = dc.client.get_auth_headers()

Performance Optimization Checklist

Use streaming for large reads: read_data_streaming() instead of read_data()
Batch writes appropriately: 500-1000 records per batch
Select only needed fields: Use fields=["Name", "Status"] parameter
Use queries to filter server-side: Don't fetch then filter locally
Cache schema: Use get_schema() once, reuse the result
Monitor concurrency: Watch for 429 errors and adjust limits
Use appropriate timeouts: Don't timeout prematurely on large operations
Use Polars for large datasets: output="polars" is 10-100x faster than pandas

Authentication Tracing & Telemetry