Diagnostics

Validate optional context before attaching it to a multimodal error.

Every error keeps class_name, error_type, original_message, operation, stage, modality, and source_kind. Missing context uses "unknown". Optional fields include mime_type, mime_type_source, size_bytes, status_code, backend, input_kind, bounded media details, and up to eight media_profiles. Paths, media bytes, and raw lower-level messages are omitted.

Stage values describe where a failure occurred:

• source_read: retrieving bytes from a source.
• sniff: identifying a media format from bytes.
• validate: checking input or options.
• probe and decode: inspecting or decoding accepted media.
• process and provider_call: processing media or calling a provider.
• configure and route: preparing a component or selecting a route.
• result: checking the output of a completed operation.
• unknown: the stage was not supplied or was invalid.

is_http_status(value)

Return whether a value is a non-boolean HTTP status code.

Parameters:

Name	Type	Description	Default
value	object	Candidate status value.	required

Returns:

Type	Description
bool	True for an integer from 100 through 599, excluding booleans.

safe_debug_info(error_class_name, supplied, *, safe_message)

Validate and bound diagnostic values before attaching them to an error.

Parameters:

Name	Type	Description	Default
error_class_name	str	Class name of the normalized error.	required
supplied	DebugInfo | None	Candidate diagnostic fields. Unsupported keys and malformed optional values are omitted. If the mapping itself cannot be read, the required fields are still returned with unknown context.	required
safe_message	str	Safe public message for the normalized error.	required

Returns:

Type	Description
DebugInfo	A DebugInfo mapping containing validated fields. The multimodal
DebugInfo	schema always includes error_type, original_message,
DebugInfo	operation, stage, modality, and source_kind; unknown
DebugInfo	context is represented by the literal "unknown".