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.