# 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

```python
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:

```python
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:

```python
# 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 {doc}`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)`.