Exceptions

Exception classes for error handling in the DocuTray SDK.

Exception Hierarchy

DocuTrayError (base)
├── APIConnectionError (network errors)
│   └── APITimeoutError (request timeout)
└── APIError (HTTP errors)
    ├── BadRequestError (400)
    ├── AuthenticationError (401)
    ├── PermissionDeniedError (403)
    ├── NotFoundError (404)
    ├── ConflictError (409)
    ├── UnprocessableEntityError (422)
    ├── RateLimitError (429)
    └── InternalServerError (5xx)

DocuTrayError

Base exception for all DocuTray SDK errors.

Arguments:

message: The error message.

APIConnectionError

Raised when the SDK cannot connect to the API server.

This includes network errors, DNS resolution failures, and other connection-level problems.

Arguments:

message: The error message. should_retry: Whether this error should be retried.

APITimeoutError

Raised when a request times out.

Arguments:

message: The error message.

APIError

Base class for errors returned by the API.

All HTTP error responses from the API are converted to subclasses of this exception. Contains rich context for debugging.

Arguments:

message: Human-readable error description. status_code: HTTP status code from the response. request_id: Request ID from X-Request-ID header for debugging. body: Parsed JSON response body (can be any JSON type). headers: Response headers.

BadRequestError

Raised when the API returns a 400 Bad Request error.

This typically indicates invalid parameters or malformed request data.

AuthenticationError

Raised when authentication fails (401 Unauthorized).

This indicates an invalid, expired, or missing API key.

PermissionDeniedError

Raised when access is forbidden (403 Forbidden).

This indicates the API key doesn't have permission for the requested operation.

NotFoundError

Raised when a resource is not found (404 Not Found).

ConflictError

Raised when there's a conflict with the current state (409 Conflict).

This typically occurs when trying to create a resource that already exists or when there's a version conflict.

UnprocessableEntityError

Raised when the request is well-formed but contains semantic errors (422).

This indicates validation errors in the request payload.

RateLimitError

Raised when rate limit is exceeded (429 Too Many Requests).

Check the retry_after property for the recommended wait time. Additional rate limit details are available in limit_type, limit, remaining, and reset_time properties when provided by the API.

Properties:

• limit : Get the maximum limit for this period.

• limit_type : Get the type of rate limit exceeded (minute, hour, day).

• remaining : Get the number of remaining requests.

• reset_time : Get the timestamp when the rate limit resets.

• retry_after : Get the recommended wait time in seconds from Retry-After header.

InternalServerError

Raised when the API returns a 5xx server error.

These errors are typically transient and can be retried.