Errors

Custom exception classes for the Ionworks API client.

Custom exception classes for the Ionworks API client.

This module defines IonworksError, which is raised when API requests fail or return error responses.

exception ionworks.api.errors.IonworksError(message: str | dict[str, Any], status_code: int | None = None)

Bases: Exception

Custom exception for Ionworks API errors.

message

A string description of the error.

Type:

str

data

Structured error data if available (e.g., from API error response).

Type:

dict[str, Any] | None

status_code

HTTP status code if applicable.

Type:

int | None

error_code

Machine-readable error code from the server (e.g., "NOT_FOUND").

Type:

str | None

__init__(message: str | dict[str, Any], status_code: int | None = None) → None

Initialize the IonworksError.

Parameters:

• message (str | dict[str, Any]) – Error message string or dict containing error details. Supports both the legacy {"detail": ...} format and the new standardized {"error_code": ..., "message": ..., "detail": ...} format.

• status_code (int | None) – Optional HTTP status code.

exception ionworks.api.errors.MeasurementProcessingError(message: str, failures: dict[str, str] | None = None)

Bases: IonworksError

Raised when a measurement upload could not be processed by the server.

Uploading a time_series measurement is a two-part operation: the request that creates the record returns as soon as the file is stored, and the steps are derived afterwards on the server. A file the server cannot read — a missing or unreadable Step column, say — is therefore rejected after the create call has already returned successfully.

The upload methods wait for that second part and raise this rather than returning a measurement that looks created but holds no usable data.

A batch wait is not fail-fast, so one of these can report several measurements at once — failures holds every one of them.

failures

Reason keyed by the id of each measurement whose processing failed. The records exist and can be inspected or deleted; they simply have no steps.

Type:

dict[str, str]

__init__(message: str, failures: dict[str, str] | None = None) → None

Initialize the error.

Parameters:

• message (str) – Why processing failed. For a batch, a summary naming each failure.

• failures (dict[str, str], optional) – Reason keyed by failed measurement id.

property measurement_id: str | None

The first — and, for a single upload, only — failed measurement id.

None if no failure was recorded. Read failures when waiting on a batch, where this reports only one of several.