Module errors 

Error codes, their classes, and the two error shapes of classify.run.

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.

The vocabulary, its classes and both error shapes are the shared model-batch rules (cortexkit-model-batch, its RULES.md §14), re-exported here at their classifier/v1 paths. What is this role’s own is which codes it answers with: ADMISSION_CODES and ITEM_CODES, the contract’s §7 tables, and BATCH_LEVEL_CODES, the Workers AI account codes its §8 maps clef’s errors to.

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_CODES

Every admission refusal code in the contract’s §7 table, in its order. The batch-level account codes, which refuse a call only when its first provider call meets one, are BATCH_LEVEL_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_CODES

Every per-item error code in the contract’s §7 table, in its order. cost_exceeded, auth_failed and model_unavailable are both admission refusals and per-item errors. The batch-level account codes are BATCH_LEVEL_CODES; answer_too_large is in the shared vocabulary, but classifier/v1 states no answer bound and never answers with it.

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_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.