Error Handling

The SDK throws typed error objects for different failure scenarios, making it simple to handle specific error conditions in your application.

Error Classes

All API errors inherit from the base Felloh::Error class. You can check the base class or target specific error types using isa().

Error Class	Status Code	Description
`Felloh::Error::Authentication`	401	Invalid API credentials or expired token
`Felloh::Error::Forbidden`	403	Insufficient permissions for the requested action
`Felloh::Error::NotFound`	404	The requested resource does not exist
`Felloh::Error::Validation`	422	Request body failed validation — check `errors` for field-level details
`Felloh::Error::RateLimit`	429	API rate limit exceeded
`Felloh::Error::Server`	5xx	Server error — the SDK automatically retries these
`Felloh::Error::Network`	—	Network failure (timeout, DNS, connection refused) — also retried automatically

The Felloh::Error Object

Every error thrown by the SDK includes structured data about the failure. Errors stringify to their message, so they work naturally with die and warn.

Accessors

Name
message
Type
string
Description
A human-readable error message. Also the string representation of the error object.
Name
status_code
Type
integer
Description
The HTTP status code. 0 for network-level failures.
Name
errors
Type
arrayref
Description
An array ref of structured error hashes returned by the API. Each includes title, message, code, type, and documentation_url.
Name
meta
Type
hashref
Description
Response metadata hash ref.
Name
request_id
Type
string
Description
Shortcut for meta->{request_id} — useful for debugging with Felloh support.

Error Handling

use Felloh::Error;

eval {
    $client->bookings->get('non-existent-id');
};
if (my $err = $@) {
    if ($err->isa('Felloh::Error::NotFound')) {
        print "Booking not found\n";
    }
    elsif ($err->isa('Felloh::Error::Validation')) {
        # Inspect field-level validation errors
        for my $error (@{ $err->errors }) {
            print "$error->{title}: $error->{message}\n";
        }
    }
    elsif ($err->isa('Felloh::Error')) {
        print "Status: " . $err->status_code . "\n";
        print "Request ID: " . $err->request_id . "\n";
    }
}

Automatic Retries

The SDK automatically retries requests that fail with a 5xx server error or a network error. Retries use exponential backoff with a maximum of max_retries attempts (default: 2).

You can configure this when creating the client:

Configuring Retries

use Felloh::Client;

my $client = Felloh::Client->new(
    public_key  => 'your-public-key',
    private_key => 'your-private-key',
    max_retries => 3,       # retry up to 3 times on 5xx/network errors
    timeout     => 15000,   # 15 second timeout per request
);