OAuthomatic::Error

- NAME
- DESCRIPTION
- SYNOPSIS
  - OAuthomatic::Error::HTTPFailure
    - METHODS
    - ATTRIBUTES
  - OAuthomatic::Error::Generic
    - ATTRIBUTES

# NAME

OAuthomatic::Error - structured exceptions thrown by OAuthomatic

# DESCRIPTION

Errors defined here allow for inspection of various error details.

# SYNOPSIS

        try {
            OAuthomatic::Error::Sth->throw({
                ident   => 'short description',
                # ... other params
            });
        } catch {
            my $error = $_;
            if ($error->isa('OAuthomatic::Error')) {
                print $error->message, "\n\n", $error->stack_trace->as_string;
                # Or use class-dependant fields
            }
        };

## OAuthomatic::Error::HTTPFailure

Object representing various communication and OAuth-protocol related failures.

        try {
            OAuthomatic::Error::HTTPFailure->throw({
                ident    => 'OAuth HTTP request failed',
                request  => $request,   # HTTP::Request
                response => $response, # HTTP::Response
            });
        } catch {
            my $error = $_;
            if ($error->isa('OAuthomatic::Error::HTTPFailure')) {
                print "$error\n";   # message
                print $error->stack_trace->as_string;  # if necessary
                if($error->is_new_client_key_required) {
                    # request new client (application) key
                } elsif($error->is_new_token_required) {
                    # redo authorization sequence
                }
                # See also other fields - code, uri, struct_detail
            }
        };

### METHODS

`is_new_client_key_required()`

  Do details of this error mean, that OAuth client key in use is no longer valid and should be replaced?

`is_new_token_required()`

  Do details of this error mean, that OAuth token in use is no longer valid and application should get new one?

### ATTRIBUTES

`request`

  http::request object containing request which caused failure

`response`

  HTTP::Response object containing obtained reply

`code`

  Shortcut. HTTP error code (400, 401, 500, ...).

`status`

  Shortcut. HTTP status line

`oauth_problem`

  If description of actual OAuth problem was detected, appropriate text code, for example `parameter_absent`, `token_revoked`, `consumer_key_rejected`, ...

  See http://wiki.oauth.net/w/page/12238543/ProblemReporting for possible values.

`detail`

  Error detail. Formatted from information available in response content (if format was not recognized, this very content by itself).

`struct_detail`

  Deserialized error detail in case output contains form-encoded data. Handles:

  form-serialized data

    Frequently used in OAuth initial protocol sequences, for example you may see here:

            {
                oauth_problem => 'parameter_absent',
                oauth_parameters_absent => 'oauth_consumer_key',
            }

  JSON error output

    For example

            {
                error => { id => '9e9c7bddeff3',
                           message => 'Object already deleted' },
            }

`method`

  Shortcut. HTTP method (GET, POST, PUT, DELETE)

`uri`

  Shortcut. URI object representing the call.

## OAuthomatic::Error::Generic

Object representing non-HTTP related exception (mostly various cases of bad parameters and programming errors).

        try {
            OAuthomatic::Error::Generic->throw({
                ident   => 'Required parameter missing',
                extra   => "Neither body, nor body_params provided."
            });
        } catch {
            my $error = $_;
            if ($error->isa('OAuthomatic::Error::Generic')) {
                print "$error\n";   # message
                print $error->stack_trace->as_string;  # if necessary
            }
        };

### ATTRIBUTES

`ident`

  Short error description

`extra`

  Additional, more elaborate, information.