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:

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:

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

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:

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:

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 — timeouts, retries, max_retries
• Cookbook: retry/backoff
• Troubleshooting (SDK)
• API errors (REST)