Python SDK Errors & Retries

Exception hierarchy, pagination, timeout, retry and batch import guidance.

Exception hierarchy

Python
ConformaError
|-- ConformaConfigError
|-- ConformaValidationError
|-- ConformaHTTPError
|   |-- ConformaAuthenticationError
|   |-- ConformaPermissionError
|   |-- ConformaNotFoundError
|   |-- ConformaConflictError
|   |-- ConformaRateLimitError
|   `-- ConformaServerError
`-- ConformaTransportError

ConformaHTTPError exposes status_code, backend code, message, details, request_id and a redacted response body.

Handling common failures

Python
from conformaesg.errors import (
    ConformaAuthenticationError,
    ConformaNotFoundError,
    ConformaRateLimitError,
    ConformaTransportError,
    ConformaValidationError,
)


try:
    supplier = client.suppliers.get("supplier-uuid")
except ConformaValidationError as exc:
    print("Invalid local payload", exc)
except ConformaAuthenticationError:
    rotate_or_replace_token()
except ConformaNotFoundError:
    mark_missing_in_source_system()
except ConformaRateLimitError as exc:
    schedule_retry_after_backoff(exc)
except ConformaTransportError as exc:
    schedule_network_retry(exc)

Timeout and retry

Timeout is mandatory, with a planned default of 30 seconds.

Automatic retry should apply only to transient failures on idempotent requests, such as:

  • GET requests
  • document metadata reads
  • 502, 503, 504
  • connection reset or similar transport errors

Do not automatically retry POST, PATCH or DELETE unless the method supports an idempotency key and the same key is reused for the same logical request.

Pagination

Paginated list methods return a Page[T] shape where the API supports pagination.

Python
page = client.suppliers.list(page=1, limit=100)


for supplier in page.items:
    process_supplier(supplier)


while page.has_next:
    page = page.next_page()

The planned Page[T] fields are items, page, page_size, total, has_next and optional next_page().

Batch imports

For ERP or PIM imports:

  • batch records in small chunks;
  • use backoff on 429, 502, 503 and 504;
  • log external ids, request ids and resource ids, not tokens or PII;
  • validate input rows with Pydantic before sending HTTP requests;
  • use idempotency keys when an endpoint supports them;
  • persist import checkpoints so jobs can resume without replaying completed work.