NAME

HTTP::API::Core::Error - Structured errors from HTTP::API::Core

DESCRIPTION

HTTP::API::Core throws structured error objects. The category value is the primary machine-readable classification. Human-readable message wording is diagnostic and should not be parsed for program logic.

The stable categories are encode, decode, transport, http, and hook.

METHODS

message, category, status, method, url

Basic structured error metadata.

retryable, retry_after

Retry-related metadata.

elapsed, request_id

Observability metadata when available.

response

Returns the associated HTTP::API::Core::Response for HTTP/decode errors, or undef when no response exists.

body, text

Return associated raw response content, or undef when there is no response.

headers

Returns a defensive copy of response headers. Without a response, returns an empty hash reference.

header($name)

Returns one response header, or undef when no response exists.

json

Explicitly decodes the associated response body as JSON using the response object's json semantics. Without a response, returns undef.

rate_limit

Returns normalized rate-limit metadata when an associated response exists.

as_string

Returns the human-readable diagnostic message. Exact message wording is not part of the machine-readable compatibility contract.

log_summary

Returns a deliberately limited single-line error summary suitable for routine operational logs. It uses only allowlisted category and HTTP method values, an HTTP status in the 100-599 range when present, and a boolean retryable flag. It never interpolates the URL, raw message, request ID, headers or response body, any of which may contain secrets. Unknown categories and methods are shown as unknown and OTHER.

Example:

warn $error->log_summary, "\n";

Use message, url and response-body accessors only in a suitably protected diagnostic context. This method does not sanitize other values that application code may add to the same log line.