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 types import SimpleNamespace

from hedron import CsrfValidationError, DoubleSubmitCookieCsrf

strategy = DoubleSubmitCookieCsrf()
request = SimpleNamespace(cookies={strategy.cookie_name: "a"}, state=SimpleNamespace())
try:
    strategy.validate(request, form_value="b", header_value=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

Structured 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