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

  The request JSON value could not be encoded.

• decode

  A response body explicitly requested as JSON could not be decoded.

• transport

  The HTTP transport failed or returned an invalid transport response.

• http

  The server returned a non-success HTTP status.

• hook

  A lifecycle hook failed.

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 the associated raw response content, or undef when there is no response. text follows the response object's text semantics and performs no charset decoding.

headers

Returns a defensive copy of response headers. When no response exists, returns an empty hash reference.

header($name)

Returns one response header, or undef when there is no response.

json

Explicitly decodes the associated response body as JSON using the response object's json semantics. Returns undef when there is no response. Invalid non-empty JSON throws a structured decode error.

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.