Module errors 

The error vocabulary every model-batch role shares: codes, their classes, and the two error shapes of a batch call.

An admission refusal answers the whole request with an ERROR frame whose body is {code, message, detail} (Refusal); it writes nothing and dispatches nothing. After admission the batch never fails as a whole: an item that could not be answered carries an ItemError in its place in the reply.

Codes are open strings on the wire: a code this crate does not list is kept as it was sent. Classes decode open too (ErrorClass::Other); a caller that meets an unknown class treats it as permanent (ErrorClass::effective), which is the safe direction.

One vocabulary serves every role, so each role’s own “this catalog row is not my kind” code (MODEL_NOT_CLASSIFIER, MODEL_NOT_EXTRACTOR) is listed here too. Which codes a role actually answers with is the role’s list (ADMISSION_CODES and ITEM_CODES in each role crate).

Modules

classes

Class names. The set is fixed for every v1 role; a new class means a new role version.

Structs

ItemError

An item’s error in a batch reply: {code, class, message, retry_after_ms?, detail?}.

ItemErrorDetail

The optional detail of an item error. Only ANSWER_TOO_LARGE sends one today; every other item error leaves it out, so its wire form is {code, class, message, retry_after_ms?}.

Refusal

An admission refusal: the body of the ERROR frame a batch call answers with, {code, message, detail}, the shape of subc_protocol::ErrorBody with a typed detail.

RefusalDetail

The detail of an admission refusal. Which members are present depends on the code (see the role contract’s table); class is always present, so a caller that meets an unknown code still knows whether to retry.

Enums

ErrorClass

An error class. Decodes open: a value other than classes is kept in ErrorClass::Other. Non-exhaustive, so a match needs a wildcard arm and adding a variant later is not a breaking change.

Constants

ACCOUNT_LIMIT_EXHAUSTED

The provider account used up its daily free allocation (Workers AI code 3036). Transient: the allocation resets. Batch-level, handled like AUTH_FAILED: an admission refusal when the call’s first provider call meets it, otherwise it stops the call and every item left unanswered carries it. Never stored, so a re-send after the reset answers the item.

ACCOUNT_NOT_ENTITLED

The provider account may not use the model: it needs a paid plan (Workers AI 5035), has not accepted the model’s agreement (5016), or is blocked (3023). Permanent until an operator acts. Batch-level, handled like AUTH_FAILED: an admission refusal when the call’s first provider call meets it, otherwise it stops the call and every item left unanswered carries it. Never stored.

ACCOUNT_WALLED

The provider account is at its limit, as the runner’s own spend guard knows before dispatch. detail.resets_at_ms when known. Transient.

ADMISSION_VOCABULARY

Every admission refusal code the vocabulary lists. A role answers with the subset its contract’s table names (its own ADMISSION_CODES).

ANSWER_TOO_LARGE

The provider answered, but one answer is larger than the bound the module states for the model, so the module does not forward it. detail.field names the field, detail.limit the bound in force and detail.size the answer’s size in bytes. Permanent and stored; a caller who wants another try re-sends under a new batch_id. classifier/v1 states no answer bound and never answers with this code.

AUTH_FAILED

The provider refused the module’s credentials (HTTP 401 or 403). Permanent. As an admission refusal: the call’s first provider call met it, so the whole call is refused and nothing is written. As a per-item error: it stopped the call, and every item the call left unanswered carries it. Never stored, so a re-send after a re-login asks the provider again.

BATCH_ID_REUSE

The batch_id names a recorded batch whose body differs. detail.field names the first differing field. Permanent.

BATCH_IN_PROGRESS

Another call holds this batch_id. detail.retry_after_ms says when to re-send. Transient. Nothing was written or dispatched.

BATCH_LEVEL_CODES

The codes that say nothing about an item and stop the call, beyond AUTH_FAILED and MODEL_UNAVAILABLE: the Workers AI account codes. Neither is ever stored as an item’s outcome.

COST_EXCEEDED

As an admission refusal: the batch’s estimated cost is over max_cost_usd; detail.estimate_usd and detail.max_cost_usd carry both. As a per-item error: answering the item would cross the batch’s ceiling. Permanent either way.

INVALID_ITEM

The provider rejected this item’s input (400, 413, 422, or another 4xx the contract does not map elsewhere). Permanent.

INVALID_PARAMS

A malformed request, or a limit exceeded. detail.field names the field, and detail.limit the limit where one applies. Permanent.

ITEM_VOCABULARY

Every per-item error code the vocabulary lists. A role answers with the subset its contract’s table names (its own ITEM_CODES).

MODEL_NOT_CLASSIFIER

classifier/v1: the model’s catalog row is not a classifier. detail.model and detail.kind name it and its kind. Permanent.

MODEL_NOT_EXTRACTOR

extractor/v1: the model’s catalog row is not an extraction model, including a row that states no kind. detail.model names it, and detail.kind its kind when the row has one. Permanent.

MODEL_UNAVAILABLE

The provider does not serve the model (HTTP 404, or a Workers AI “no such model” code). Permanent. As an admission refusal, detail.model names the model; the call’s first provider call met it, so the whole call is refused and nothing is written. As a per-item error: it stopped the call, and every item the call left unanswered carries it. Never stored, so a re-send after a catalog fix asks the provider again.

MODEL_UNKNOWN

The model is not in the runner’s catalog. detail.model names it. Permanent.

PROVIDER_ERROR

The provider answered 5xx or 408, or the transport failed, after the runner’s own retries. Transient.

PROVIDER_REFUSED

The provider refused the content. Permanent.

RATE_LIMITED

The provider answered 429 or 529 after the runner’s own retries. retry_after_ms when the provider gave one. Transient. It stops the call: the items after it that would need a provider call are not sent, and carry rate_limited too, unstored, so a re-send retries them.

Functions

admission_class

The class of an admission refusal code this crate lists, None for any other code.

is_batch_level

Whether code says nothing about the item it came back for: never stored, stops the call, and refuses the call at admission when its first provider call meets it.

item_class

The class of a per-item error code this crate lists, None for any other code.