Errors

Hierarchy

TurboOcrError
├── APIConnectionError       # transport-level
│   ├── Timeout
│   ├── NetworkError
│   └── ProtocolError
├── InvalidParameter         # 4xx: bad params / headers / dims
├── EmptyBody                # 4xx: empty body / batch / PDF
├── LayoutDisabled           # asked for layout when server has it off
├── ImageDecodeError         # bad bytes / bad base64
├── DimensionsTooLarge       # image / PDF over server limits
├── PoolExhausted            # "Server at capacity"
├── PdfRenderError           # PDF rasterization failed
└── ServerError              # 5xx, no specific code

Server-side exceptions carry .code, .status_code, and .payload. Transport exceptions inherit from APIConnectionError.

Common failures

Symptom	Cause	Fix
NetworkError: Connection refused	server not running	start the docker container
DimensionsTooLarge	image > MAX_IMAGE_DIM (default 16384)	downscale or raise the server limit
LayoutDisabled	server started with DISABLE_LAYOUT=1	restart without that env var
PoolExhausted	server queue full	retry with backoff, or scale PIPELINE_POOL_SIZE
Timeout	per-request timeout hit	pass timeout=N or raise RetryPolicy.attempts

Reference

TurboOcrError

TurboOcrError(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: Exception

ATTRIBUTE	DESCRIPTION
code
status_code
payload

code instance-attribute

code = code

status_code instance-attribute

status_code = status_code

payload instance-attribute

payload = payload or {}

APIConnectionError

APIConnectionError(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

NetworkError

NetworkError(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: APIConnectionError

Timeout

Timeout(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: APIConnectionError

ProtocolError

ProtocolError(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: APIConnectionError

InvalidParameter

InvalidParameter(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

EmptyBody

EmptyBody(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

LayoutDisabled

LayoutDisabled(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

ImageDecodeError

ImageDecodeError(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

DimensionsTooLarge

DimensionsTooLarge(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

PoolExhausted

PoolExhausted(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

PdfRenderError

PdfRenderError(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError

ServerError

ServerError(message: str, *, code: str | None = None, status_code: int | None = None, payload: dict[str, Any] | None = None)

Bases: TurboOcrError