Error Handling#

All API errors are raised as IonworksError exceptions. The error carries a human-readable message, an optional structured data dictionary, and the HTTP status_code when available.

Basic usage#

from ionworks import Ionworks, IonworksError

client = Ionworks()

try:
    spec = client.cell_spec.get("invalid-id")
except IonworksError as e:
    print(f"Message: {e.message}")
    print(f"Status code: {e.status_code}")
    print(f"Data: {e.data}")

Correlation IDs#

When an HTTP error occurs, the client automatically prints the x-correlation-id header from the response (if present). This correlation ID can be used to trace the request in backend logs for debugging purposes:

try:
    measurement = client.cell_measurement.get("invalid-id")
except IonworksError:
    # x-correlation-id: abc123-def456-ghi789
    # Will be printed automatically if present in the response
    pass

Use this correlation ID when reporting issues or requesting support, as it helps identify the specific request in server logs.

Common error codes#

Status

Meaning

Typical cause

401

Unauthorized

Invalid or expired API key

404

Not Found

Resource ID does not exist

409

Conflict

Resource with the same name already exists — use create_or_get()

422

Unprocessable Entity

Invalid request payload

500

Internal Server Error

Server-side issue — contact support

Avoiding duplicates#

Several resources support create_or_get(), which returns the existing record when a name collision occurs instead of raising a 409 error. This is particularly useful in scripts that may be run more than once:

# These are safe to call repeatedly
cell_spec = client.cell_spec.create_or_get({...})
cell_instance = client.cell_instance.create_or_get(cell_spec.id, {...})
measurement = client.cell_measurement.create_or_get(cell_instance.id, {...})

Debugging tips#

  • When an HTTP error occurs, the client automatically prints the x-correlation-id header if present. Use this ID when reporting issues to help trace the request in backend logs.

  • Set verbose=True on client.simulation.wait_for_completion() to see polling status.

  • Check pipeline.error after a failed pipeline run for a server-side traceback.

  • If you receive a ValueError on client initialization, verify that the IONWORKS_API_KEY environment variable is set (see Authentication).

  • If requests are timing out, increase the timeout: client = Ionworks(timeout=30).

  • The client automatically retries failed requests (default: 5 retries). Adjust with max_retries if needed: client = Ionworks(max_retries=3).