Errors & fail behavior
Fail-closed vs fail-open
If Kelhe can't score an action — the engine is unreachable, the key is rejected,
or the quota is exhausted — the on_api_error setting decides what happens to
the tool call:
from kelhe import Kelhe
from kelhe.client import OnApiError
Kelhe(on_api_error=OnApiError.FAIL_CLOSED) # default: block the action
Kelhe(on_api_error=OnApiError.FAIL_OPEN) # let the action run unscored
The default is fail-closed: a risk layer should never silently allow an
action it couldn't score. Choose FAIL_OPEN only when availability matters more
than the guarantee. This fallback applies to any scoring failure, not just
network outages.
Exception types
The engine client raises typed errors (all subclass KelheError):
| Exception | When |
|---|---|
KelheAuthError | API key missing or rejected (HTTP 401 / 403). |
KelheQuotaError | Account out of credits or over quota (HTTP 402 / 429). |
KelheNetworkError | Engine unreachable, timed out, or a 5xx. |
Inside a guarded tool these are handled for you by on_api_error — you don't
need to catch them. They surface directly only if you call the engine yourself.