NAME
SelectPdf::DemoException - Base class for the typed errors raised by the keyless demo endpoint.
SYNOPSIS
The demo endpoint (used when SelectPdf::HtmlToPdfClient is constructed without an API key) reports rate limits, rejected URLs and unsupported features as structured JSON. The client turns those into exception objects that are thrown with die. They stringify to a readable message, so code that only prints $@ keeps working, and they can be inspected programmatically:
use SelectPdf;
eval {
my $client = SelectPdf::HtmlToPdfClient->new(); # keyless demo mode
$client->convertUrlToFile("https://selectpdf.com", "Test.pdf");
};
if (my $err = $@) {
if (ref $err && $err->isa('SelectPdf::DemoRateLimitException')) {
# reason is one of: per_ip, daily_cap, concurrency
print "Demo rate limit (" . $err->reason() . "). Retry after " . $err->retryAfter() . "s. Upgrade: " . $err->upgradeUrl() . "\n";
}
elsif (ref $err && $err->isa('SelectPdf::DemoSafetyException')) {
print "Demo safety guard rejected '" . $err->field() . "' (reason=" . $err->reason() . ").\n";
}
elsif (ref $err && $err->isa('SelectPdf::DemoUnsupportedException')) {
print "Feature '" . $err->field() . "' not available in demo mode. Upgrade: " . $err->upgradeUrl() . "\n";
}
else {
print "An error occurred: $err\n";
}
}The classes are:
SelectPdf::DemoRateLimitException- HTTP 429 or 503, the demo rate limit was reached.SelectPdf::DemoSafetyException- HTTP 400, a URL field references a non-public host.SelectPdf::DemoUnsupportedException- HTTP 400 (or raised locally before the request is sent), the feature is not available in demo mode.
All of them derive from SelectPdf::DemoException.
METHODS
message
The error message. The object also stringifies to this message.
statusCode
HTTP status code returned by the server. Zero for a SelectPdf::DemoUnsupportedException raised by the local client guard before the request was sent.
responseBody
The raw JSON body the server returned, for diagnostics / logging. Undef when the exception was raised by the local client guard.
NAME
SelectPdf::DemoRateLimitException - Thrown when the demo endpoint refuses a request because of a rate limit (HTTP 429 or 503).
METHODS
statusCode
HTTP status code returned by the server (429 or 503).
reason
Machine-readable rate-limit reason: per_ip (the source IP exceeded its hourly conversion budget), concurrency (too many demo conversions are running right now) or daily_cap (the global demo budget for today has been reached).
retryAfter
Seconds the client should wait before retrying (parsed from the Retry-After response header). Zero if absent.
upgradeUrl
URL the user can visit to upgrade out of demo mode.
responseBody
The raw JSON body the server returned.
NAME
SelectPdf::DemoSafetyException - Thrown when the demo safety guard rejects a request because a URL field references a non-public host (HTTP 400).
METHODS
statusCode
HTTP status code returned by the server (400).
field
Which input field was rejected: url, html, base_url, header_url, footer_url.
reason
Why the field was rejected: blocked_host, private_ip, loopback, link_local, cgnat, metadata, multicast, bad_scheme, bad_url, inline_internal_ref:<sub-reason>.
responseBody
The raw JSON body the server returned.
NAME
SelectPdf::DemoUnsupportedException - Thrown when the caller tried to use a feature that demo mode does not support, most commonly PDF passwords (HTTP 400). For paid keys, this exception is never thrown.
METHODS
statusCode
HTTP status code returned by the server (400). Zero if the exception was raised by the local client guard before the request was sent.
field
Which feature is unsupported: user_password, owner_password, async.
upgradeUrl
URL the user can visit to upgrade out of demo mode.
responseBody
The raw JSON body the server returned. Undef when raised by the local client guard.