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

import ionworks as iw

client = iw.api.Client()

try:
    spec = client.cell_spec.get("invalid-id")
except iw.api.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:

import ionworks as iw

try:
    measurement = client.cell_measurement.get("invalid-id")
except iw.api.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 = iw.api.Client(timeout=30).

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