Python SDK — Errors

The Python SDK defines a hierarchy of exception classes for handling API errors. All exceptions are importable from pii_redactor_sdk.

Exception Hierarchy


ApiError
├── AuthenticationError   (401, 403)
├── NotFoundError         (404)
├── ValidationError       (422)
└── RateLimitError        (429)

PollingTimeoutError       (job polling exceeded max wait)

ApiError

Base class for all API errors. Contains the HTTP status code, error message, and the raw response.


class ApiError(Exception):
    status_code: int
    message: str
    response: dict | None

Attribute	Type	Description
`status_code`	`int`	HTTP status code
`message`	`str`	Human-readable error message
`response`	`dict \| None`	Raw JSON response body, if available

AuthenticationError

Raised when the API key is missing, invalid, or lacks the required scopes. Maps to HTTP 401 and 403 responses.


class AuthenticationError(ApiError):
    pass

NotFoundError

Raised when a requested resource (job, policy, API key) does not exist. Maps to HTTP 404.


class NotFoundError(ApiError):
    pass

ValidationError

Raised when the request body fails server-side validation. Maps to HTTP 422.


class ValidationError(ApiError):
    pass

RateLimitError

Raised when the API rate limit is exceeded. Maps to HTTP 429. Includes a retry_after field indicating how many seconds to wait before retrying.


class RateLimitError(ApiError):
    retry_after: float | None

Attribute	Type	Description
`retry_after`	`float \| None`	Seconds to wait before retrying, from the `Retry-After` header

PollingTimeoutError

Raised when polling a job exceeds the maximum wait time. This is not an HTTP error — it is raised client-side when a job does not complete within the expected timeframe.


class PollingTimeoutError(Exception):
    job_id: str
    elapsed: float

Attribute	Type	Description
`job_id`	`str`	ID of the job that timed out
`elapsed`	`float`	Total seconds spent polling

Error Handling Example


from pii_redactor_sdk import (
    PiiRedactor,
    ApiError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)
 
client = PiiRedactor(api_key="pk_live_...")
 
try:
    result = client.redact.text(text="John Smith's SSN is 123-45-6789")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except NotFoundError as e:
    print(f"Resource not found: {e.message}")
except ApiError as e:
    print(f"API error {e.status_code}: {e.message}")

Handling Job Polling Timeout


from pii_redactor_sdk import PiiRedactor, PollingTimeoutError
 
client = PiiRedactor(api_key="pk_live_...")
 
try:
    job = client.redact.uri(input_uri="s3://bucket/large-file.pdf")
    # If using a polling helper:
    # completed = poll_job(client, job.id, timeout=120)
except PollingTimeoutError as e:
    print(f"Job {e.job_id} did not complete after {e.elapsed}s")
    # Check status manually
    job = client.jobs.get(e.job_id)
    print(f"Current status: {job.status} ({job.progress_pct}%)")