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.