Troubleshooting and FAQ

Common issues when using dealcloud-sdk with the DealCloud API. The SDK uses intapp-rest-client for HTTP; retry behavior, 429 handling, and transport errors are documented there.

HTTP 429 (rate limiting)

Symptoms: HttpError with status_code == 429, or slow bulk jobs that eventually fail.

What to check:

• Tune responseRetrySettings / query concurrency in DealCloudConfig (and underlying RetryConfig on the REST client).
• Reduce parallelism: read_concurrency, parallel_get / parallel_post batch sizes, or async concurrency.
• Read retry_after on HttpError when present (error handling).

Authentication and tokens

Symptoms: 401, 403, or unexpected token errors.

What to check:

• Correct site_url, client_id, and client_secret (Authentication).
• OAuth scope and clock skew on the host running the SDK.
• For low-level token behavior, see Authentication (intapp-rest-client).

read_data() requires output

Symptoms: ValueError mentioning output.

The output argument is required (migration from legacy defaults). Pass output="pandas", "list", "polars", or "polars_lazy" explicitly. See Migration.

Cells: fields vs old field_ids docs

Use get_cells(..., fields=[...]) with field IDs or field API names. The parameter name is fields, not field_ids.

Cells: delete_cells removed my rows

delete_cells(object_id, entry_ids) calls the API to delete entries (rows), not to clear a single field. To clear or update field values, use write_cells or row APIs. See Cell operations.

File download path

download_file(entry_id, field_id, ...) does not take object_id in the path (matches API entryfiles/{entryId}/fields/{fieldId}). See Files and the API reference.

Verbose logging

Symptoms: Need request IDs, retry lines, or HTTP detail.

What to check:

• Python logging levels on dealcloud_sdk and httpx (Logging).
• Intapp client docs: Logging, Errors, Tracing for OpenTelemetry.

Where to get more help

• Error handling — SDK exceptions and patterns
• API reference — consolidated method list
• Intapp REST Client — HTTP client, SSL, logging, tracing