Skip to content

The API

Errors

Every error Jeff can raise is listed in contract/errors.yaml (its server-side name, HTTP status and meaning), and every SDK maps that name back to the same exception class. An error body over HTTP is {"error": {"type", "message", "details"}}, and every response — success or error — carries an x-request-id header; quote it when asking the server's operator about a failure.

A few entries have no HTTP status at all: they occur only on your machine (no server involved) or on the raw engine socket, and can never reach an HTTP or channel client.

ErrorHTTP statusMeaning
JeffError500Base class; never raised directly.
ContractError500A document does not match its contract schema.
ManifestError500An adapter manifest or the routing tree is invalid.
InvalidReference422A function reference is malformed.
UnknownFunction404No function or adapter in the catalogue has this ID, alias or version.
NotInstalled424The function exists but its adapter is not loaded.
MissingContext422Required context fields are missing.
UnknownContext422Context fields the function does not have.
MissingLabels422The function takes its labels from the caller and none were given.
InvalidLabels422Labels are given where they are fixed, or keys collide or are malformed.
TooManyLabels422More labels than the function was trained on.
TooManyHandles422A channel connection already holds the most bound-function handles it may (1024); release one first.
InterfaceMismatch422A function was called through an interface it does not implement.
LowConfidence409The decision abstained and on_low_confidence was 'error'; details carry the decision.
EscalationFailed502An escalation step failed.
EscalationBudgetExceeded504An escalation ran past its budget_ms.
InvalidPolicy422on_low_confidence is not valid for this call.
GraphError422A decision graph is invalid or cannot run.
RuntimeMissingNot sent over HTTPLocal mode needs the jeff-runtime package.
ProprietaryWeightsNot sent over HTTPA proprietary adapter's weights need a licence or a local folder.
CalibrationErrorNot sent over HTTPCalibration cannot reach the target or has no data.
EngineError500The engine failed or broke its contract.
InputTooLong422The request is longer than the token limit; it was refused, never truncated.
BackendUnavailable503The engine backend cannot run on this machine.
Busy529The engine queue is full; retry after the Retry-After seconds.
DeadlineExceeded504The request's deadline passed before it ran.
ProtocolMismatchNot sent over HTTPThe two ends of the engine socket speak different protocol versions.
NotReady503The engine is still starting.
Unauthorised401Missing or invalid credentials.
NotLicensed403The caller's token does not include this proprietary function's licence.
RateLimited429The caller exceeded its rate limit; retry after the Retry-After seconds.
UsageLimitReached402The account has used its input-token allowance for the billing period; calls resume when the next period starts.
InvalidRequest422The request does not match the API schema.
Conflict409The request does not fit the current state of the factory run.
FactoryOff403The factory is off on this server.

Busy and RateLimited both carry retry_after_s in their details: wait that many seconds before trying again. A LowConfidence error's details carry the decision that abstained, so the caller can inspect it even when it asked for "error" rather than "return" (see Escalation).

UsageLimitReached is checked when a request first calls the model, so listing functions and binding a function on the channel still work after the allowance is reached, and a request that starts within the allowance runs to completion. Usage counts the input tokens of every request the model answered, even when a later part of the same API request fails (for example, the second function of a batch): those tokens have already been processed.

Next steps