Skip to content

Public exceptions and failure types

Stability

Classifications for this surface are recorded in STABILITY.md. Package maturity (Beta/Alpha) is separate from API level.

This page catalogs public exception classes and a few related failure types re-exported from hedron (plus helpers that raise ordinary ValueError). It is not a full HTTP error catalog — see Error codes for diagnostic codes.

Type Typical HTTP Role
CsrfValidationError 403 CSRF strategy validation failed
FragmentRegionError 403 Unauthorized HTMX target / region
ByteRangeNotSatisfiable 416 Media byte-range cannot be satisfied
StorageQuotaExceeded app-owned Browser storage quota
BrowserStorageUnavailable app-owned Client storage API missing

Prefer catching these by type when writing host adapters or shared libraries. HTTP mapping for CSRF failures remains 403 on built-in profiles — see CSRF composition.

Exceptions

CsrfValidationError

Raised by pluggable CSRF strategies (DoubleSubmitCookieCsrf, SessionTokenCsrf) when validate(...) fails. Host adapters map this to HTTP 403.

from hedron import CsrfValidationError, DoubleSubmitCookieCsrf

strategy = DoubleSubmitCookieCsrf()
try:
    strategy.validate(cookie="a", form_token="b", header_token=None)
except CsrfValidationError:
    ...  # typically → HTTP 403

Typical message: "CSRF validation failed".

hedron_core.csrf_strategy.CsrfValidationError

Bases: Exception

Raised by strategies when CSRF validation fails (hosts map to HTTP 403).

FragmentRegionError

Raised when an HTMX HX-Target (or resolved region_id) is not an authorized FragmentRegion. Subclass of ValueError with .requested, .declared, and .code (default HED-HTMX-0001). FastAPI/HedronRoute and the Flask/Django adapters map this to HTTP 403.

from hedron import FragmentRegionError, InteractionPolicy
from hedron_core.interaction import authorize_htmx_target

policy = InteractionPolicy(declared_regions=())
try:
    authorize_htmx_target(policy, "#main", is_htmx=True)
except FragmentRegionError as exc:
    assert exc.code == "HED-HTMX-0001"
    ...  # typically → HTTP 403

See Interaction and HTMX interactions.

hedron_core.interaction.FragmentRegionError

Bases: ValueError

HX-Target is not an authorized declared fragment region.

ByteRangeNotSatisfiable

Raised when a media byte-range request cannot be satisfied. Subclass of ValueError with a .size attribute. Media helpers map this to HTTP 416 and Content-Range: bytes */{size}.

See Media downloads.

hedron.builtins.media.ByteRangeNotSatisfiable

Bases: ValueError

Raised when a Range header is present but cannot be satisfied (HTTP 416).

StorageQuotaExceeded

Raised by BrowserStorage.set when a namespace exceeds max_entries or max_bytes. Subclass of RuntimeError. This is a quota failure, not an authorization decision — client storage remains spoofable.

Related: BrowserStorageUnavailable when the client storage API is unavailable.

hedron_core.browser.StorageQuotaExceeded

Bases: RuntimeError

Raised when a set would exceed entry or byte quotas.

The following public helpers appear on this page historically; they are not raised exception types. Prefer their component/API pages for day-to-day use.

Directory upload validation

validate_directory_upload(...) and DirectoryUploadFile support DirectoryUpload. Validation failures raise ValueError (path traversal, max_files, max_total_size) — not a dedicated exception class.

hedron_core.builtins.forms_extra.DirectoryUploadFile dataclass

Normalized directory-upload entry for server-side validation.

hedron_core.builtins.forms_extra.validate_directory_upload(files, *, max_files, max_total_size)

Validate directory upload names, counts, and total size (server-side).

Browser helpers

ViewportHint and redact_cookie_value are public browser-context helpers. Cookie redaction is for logs/diagnostics — never treat client hints as authorization.

hedron_core.browser.ViewportHint dataclass

Client-reported viewport dimensions (spoofable).

Return a display-safe cookie value; secret-looking names are fully redacted.

Inference presentation types

Typed rows used by inference UI components (not raised errors):

Type Used by
PredictionScore PredictionLabel
DialogueTurn Dialogue
GalleryItem Gallery

See Inference and BUILT_INS.

hedron_core.builtins.model_demo.PredictionScore

Bases: Props

hedron_core.builtins.model_demo.DialogueTurn

Bases: Props

hedron_core.builtins.media.GalleryItem

Bases: Props

One gallery entry: image asset plus optional selection link and caption.

See also