> For the complete documentation index, see [llms.txt](https://docs.layerlens.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layerlens.ai/more-in-this-section-9/errors-1.md).

# Errors

SDK exception hierarchy — StratixError → APIError → APIStatusError → HTTP-status-specific exceptions.

## Top-level imports

The SDK exports five exception classes from the top-level package:

```python
from layerlens import (
 StratixError, # base for all SDK errors
 APIError, # base for all API-related errors
 BadRequestError, # 400
 AuthenticationError, # 401
 NotFoundError, # 404
)
```

For other exception types, import from `layerlens._exceptions`:

```python
from layerlens._exceptions import (
 APIConnectionError,
 APITimeoutError,
 APIResponseValidationError,
 APIStatusError,
 PermissionDeniedError,
 ConflictError,
 UnprocessableEntityError,
 RateLimitError,
 InternalServerError,
)
```

## Full hierarchy

```
StratixError (base for all SDK errors)
└── APIError (base for all API-related errors)
 ├── APIConnectionError (network / connection issues)
 │ └── APITimeoutError (request timed out)
 ├── APIResponseValidationError (response shape didn't match expected schema)
 └── APIStatusError (HTTP 4xx / 5xx status)
 ├── BadRequestError (400)
 ├── AuthenticationError (401)
 ├── PermissionDeniedError (403)
 ├── NotFoundError (404)
 ├── ConflictError (409)
 ├── UnprocessableEntityError (422)
 ├── RateLimitError (429)
 └── InternalServerError (500+)
```

## Catch-most-specific-first

```python
import os
from layerlens import Stratix, StratixError, APIError, BadRequestError, NotFoundError, AuthenticationError

client = Stratix(api_key=os.environ.get("LAYERLENS_STRATIX_API_KEY"))

try:
 result = client.models.get_by_id("nonexistent-id")
except NotFoundError as e:
 print(f"Not found (HTTP {e.status_code}): {e.message}")
except AuthenticationError as e:
 print(f"Auth failed: refresh your API key — {e.message}")
except BadRequestError as e:
 print(f"Validation: {e.message}")
except APIError as e:
 print(f"API error: {e.message}")
except StratixError as e:
 print(f"Client error: {e}")
```

## Exception properties

All `APIStatusError` subclasses expose:

| Property      | Description                                    |
| ------------- | ---------------------------------------------- |
| `status_code` | HTTP status code (e.g. `404`)                  |
| `message`     | Human-readable error message from the API      |
| `response`    | The underlying httpx response object           |
| `request_id`  | Server-side request ID for support correlation |

## Retry semantics

The SDK automatically retries on these conditions:

* `APIConnectionError` (network blip)
* `RateLimitError` (429) — respects `Retry-After` header
* `InternalServerError` (500, 502, 503, 504) — exponential backoff

Default retry configuration:

| Setting     | Default                                              |
| ----------- | ---------------------------------------------------- |
| Max retries | 2 (configurable via `Stratix(max_retries=N)`)        |
| Backoff     | Exponential, jittered                                |
| Timeout     | 10 minutes (configurable via `Stratix(timeout=...)`) |

To disable retries:

```python
client = Stratix(max_retries=0)
```

## Common error scenarios

### Missing API key

```
StratixError: The api_key client option must be set either by passing api_key to the client
or by setting the LAYERLENS_STRATIX_API_KEY environment variable
```

**Fix:** export the env var or pass `api_key=` explicitly.

### 404 on `get_by_key`

`get_by_key` is case-sensitive. Check the exact key string in the catalog (`openai/gpt-4o`, not `OpenAI/GPT-4o`). If still failing, fall back to:

```python
models = client.models.get(type="public", name="gpt-4o")
```

### Trace upload — 50 MB limit

Trace files (`.json` / `.jsonl`) must be under 50 MB. Split larger datasets into chunks.

## See also

* [Client configuration](/more-in-this-section-9/client.md) — timeouts, retries, max\_retries
* [Cookbook: retry/backoff](/more-in-this-section-9/retry-backoff.md)
* [Troubleshooting (SDK)](/more-in-this-section-9/troubleshooting.md)
* [API errors (REST)](/more-in-this-section-9/errors.md)