Errors

The SDK raises four distinct exception types. Each maps to a specific failure mode — match them explicitly rather than catching Exception.

PromptNotReleasedInEnvironmentError

from elsai_prompts.prompt_manager import PromptNotReleasedInEnvironmentError

Raised when the active version of the requested prompt exists, but is not released to the environment you asked for. Maps to HTTP 409 on the wire.

Attributes

prompt_name — str — Name of the prompt that was requested.

requested_environment — str — The environment string passed (constructor default or per-call override).

available_environments — list[str] — The environments the active version is released to, if any.

Message format

Active version of prompt '<name>' is not released to environment '<env>'.
Available environments: [<envs>] (or 'none').

Recovery patterns

from elsai_prompts.prompt_manager import PromptNotReleasedInEnvironmentError

# Pattern 1: fail loudly (production)
try:
    prompt = pm.get_active_prompt_version("welcome_email")
except PromptNotReleasedInEnvironmentError:
    logger.exception("prompt_not_released")
    raise

# Pattern 2: graceful fallback
try:
    prompt = pm.get_active_prompt_version("footer_message")
    text = prompt.render({})
except PromptNotReleasedInEnvironmentError:
    text = "© 2026 Acme Inc."

# Pattern 3: introspect and act
try:
    prompt = pm.get_active_prompt_version("welcome_email")
except PromptNotReleasedInEnvironmentError as e:
    if "testing" in e.available_environments:
        alert_release_team(e.prompt_name)
    raise

See Error handling( for full patterns.

requests.exceptions.HTTPError

Raised by the underlying requests library on non-2xx responses other than 409 (which is handled specially). The most common case is 404.

The 404 is intentionally generic — the server collapses these reasons into a single 404 to avoid leaking which resource is missing:

• API key invalid or revoked
• Project doesn't exist
• Prompt doesn't exist in this project
• No active version set
• (On-prem) Key owner is not a member of the project's organization

Handling

import requests

try:
    prompt = pm.get_active_prompt_version("welcome_email")
except requests.exceptions.HTTPError as e:
    if e.response is not None and e.response.status_code == 404:
        logger.error("prompt_unavailable", extra={"prompt_name": "welcome_email"})
    elif e.response is not None and 500 <= e.response.status_code < 600:
        logger.exception("platform_5xx")
        # Retry-with-backoff appropriate
    else:
        raise

requests.exceptions.RequestException (and subclasses)

The parent class for network-layer failures. Common subclasses:

Subclass	When
requests.exceptions.Timeout	Request exceeded timeout seconds
requests.exceptions.ConnectionError	DNS failure, connection refused, TLS error
requests.exceptions.HTTPError	Non-2xx response (see above)
requests.exceptions.ChunkedEncodingError	Stream interrupted mid-response

These are typically transient — retry with backoff is appropriate.

import requests
import time

def fetch_with_retry(name, retries=3, backoff=0.5):
    last_exc = None
    for attempt in range(retries):
        try:
            return pm.get_active_prompt_version(name)
        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
            last_exc = e
            time.sleep(backoff * (2 ** attempt))
    raise last_exc

KeyError

Raised when the server's response is missing the content field — i.e., the response is shaped wrong. This should not happen in steady state; if it does, it indicates a server-side bug or a version skew between client and platform.

try:
    prompt = pm.get_active_prompt_version("welcome_email")
except KeyError:
    logger.exception("malformed_response")
    raise

Recovery: log, alert, page the team. The SDK can't recover from this.

ValueError

Raised by the constructor when required arguments are missing or empty.

Argument	Message
api_key=""	api_key is required.
project_id=""	project_id is required.
environment=""	environment is required. Pass the runtime environment of this code...
base_url=None and PROMPT_MANAGER_API_URL unset (on-prem)	Base URL for Prompt Manager API is not set...

Also raised by get_active_prompt_version_for_environment if the per-call environment argument is empty.

These are programming bugs, not runtime conditions — fix the call site rather than catching them in production code.

Exception inheritance map

Exception
├── ValueError                                  ← constructor / per-call validation
├── KeyError                                    ← malformed response
└── requests.exceptions.RequestException
    ├── requests.exceptions.Timeout
    ├── requests.exceptions.ConnectionError
    └── requests.exceptions.HTTPError           ← 404, 5xx, etc.

PromptNotReleasedInEnvironmentError              ← 409 (subclass of Exception)

Decision matrix

Failure	Exception	Transient?	Recommended response
Bad construction args	ValueError	No	Fix at startup
Invalid key	HTTPError 404	No	Alert, then revoke/replace
Prompt not found	HTTPError 404	No	Check name in console
No active version	HTTPError 404	No	Publish a version
Wrong env	PromptNotReleasedInEnvironmentError	No	Release the version, or change environment=
5xx	HTTPError 5xx	Yes	Retry with backoff
Timeout	Timeout	Yes	Retry with backoff
DNS / connection	ConnectionError	Yes	Retry with backoff
Malformed response	KeyError	No	Log, alert, page

See also