NAME

InternetData::Error - why a request failed

SYNOPSIS

my $databases = eval { $client->database->list };
if (my $err = $@) {
    die $err unless ref $err && $err->isa('InternetData::Error');
    warn $err->kind, ': ', $err->message;
    warn 'worth retrying' if $err->retryable;
}

DESCRIPTION

Every failure raised by this library is one of these objects. It stringifies to its message, so warn $@ and die $@ read as they would with an ordinary string exception.

METHODS

kind

One of bad_request, unauthorized, forbidden, rate_limited, quota_exceeded, server_error or network.

rate_limited and quota_exceeded both arrive as HTTP 429 and are not the same thing. A rate limit is the API protecting itself, carries Retry-After, and retrying works. A spent quota carries no such header, and retrying will not help until the window rolls over or the limit is raised. The header is the only thing that separates them.

message

The API's own result code - UNAUTHORIZED, NOT_LICENSED, LICENSE_EXPIRED, UNKNOWN_DATASET, INVALID_FORMAT, NOT_AVAILABLE and so on - or a fallback naming the status when the response carried no envelope.

The codes are deliberately not an enum on the wire, so one added later stays readable to a client built today. Branch on "kind" for behavior and read this when you need to tell two refusals with the same status apart: NOT_LICENSED and LICENSE_EXPIRED are both 403.

status

The HTTP status, or undef for a transport failure.

retry_after

Seconds to wait, when the API said so.

retryable

Whether retrying this exact request could succeed. True for rate_limited, server_error and network, false for everything else - including every 4xx, so a database id that does not exist fails once rather than three times.