Responses, pagination, and errors

Cloudflare JSON responses commonly contain success, result, and sometimes result_info. A list method follows every available page and returns a flat array reference:

my $buckets_ar=$api_or->r2()->list_buckets();

This is convenient for ordinary result sets, but it issues as many requests as necessary and keeps every item in memory. A per_page argument can change the number of items requested from Cloudflare at once, but it does not limit the final result. Use the corresponding _page() method when the result may be large. It returns a lazy HTTP::API::Core::Pagination object:

my $page_or=$api_or->r2()->list_buckets_page(per_page => 100);
while (defined(my $bucket_hr=$page_or->next())) {
    print $bucket_hr->{'name'}, "\n";
}

The corresponding _page_response() method makes exactly one request and returns the complete decoded Cloudflare response hash. Use it when you need result_info, page boundaries, or other response fields:

my $page_hr=$api_or->r2()->list_buckets_page_response(per_page => 100);
my $buckets_ar=$page_hr->{'result'}{'buckets'};

The exact response and pagination fields depend on the endpoint. A supplied page or cursor selects the starting point for a list method or paginator. full_response is unavailable for list method families; use _page_response() instead. The command-line client remains explicitly page-oriented: a list action fetches one page unless --paginate is supplied, and paginated output preserves page boundaries.

An HTTP or transport failure is thrown as an HTTP::API::Core::Error. A successful HTTP response whose decoded Cloudflare response says success: false is thrown as Cloudflare::API::Error; it retains errors(), messages(), and the underlying response(). This validation also applies when a paginator fetches a later page. For example:

my $result_hr=eval { $api_or->r2()->get_bucket('my-app-assets') };
if (my $error=$@) {
    if (ref($error) && $error->isa('Cloudflare::API::Error')) {
        warn "Cloudflare rejected the request: $error\n";
    }
    else {
        die $error;
    }
}

Note

A missing account ID or invalid local argument may also raise an ordinary Perl exception before any request is made. Keep tokens and secret request bodies out of exception logs.