NAME

Business::CPI::Role::Exception - Exceptions from the gateway

VERSION

version 0.922

DESCRIPTION

This role is meant to be used by the drivers to encapsulate gateway exceptions, put them in the required format, and rethrowing them as real Perl exceptions (using Throwable).

ATTRIBUTES

type

The type is a string, that will contain one of the predefined values mentioned below. The examples will refer to HTTP Status, but the exceptions are not limited to HTTP errors. The gateway API doesn't need to be RESTful.

invalid_data

Part or all of the data provided to the gateway was not valid. Example: the buyer name contained numbers.

incomplete_data

The data sent to the gateway was not complete. Example: the buyer name was missing.

invalid_request

The request could not be made because it's formatted in a way the gateway did not expect. Most likely this is due to an error in the Business::CPI driver.

Example: the gateway responded with HTTP status 405, 406, 417, etc, supposing a RESTful API.

resource_not_found

Some item in the request references an item which was not found in the gateway, or the request returns HTTP status 404.

unauthorized

The API user is not authorized to make this request (HTTP Status 403).

unauthenticated

The API user is not properly authenticated (HTTP Status 401).

duplicate_transaction

The transaction has already been executed. Example: a shopping cart which has already been payed, or a refund that has already been requested.

The gateway API could respond HTTP 200 OK, but it's not always the case. When it responds with error, and this is the reason, the type will be duplicate_transaction.

rejected

Some business logic in the gateway determined that this request could not be completed. Example: requesting a refund of a payment which is still processing. That is, the payment exists (not "resource_not_found"), the request is valid, the data is complete and valid, but it cannot be fulfilled.

gateway_unavailable

The gateway API responded with one of the following HTTP Status, for example: 408, 502, 503 or 504. That is, either a timeout occurred, or the server reported to be unavailable.

gateway_error

There was an internal server error in the gateway.

unknown

The gateway threw some kind of exception that Business::CPI was unable to parse.

message

A human readable message of the error, preferably in English, either generated by Business::CPI, the driver, or the gateway. This serves only for debuging purposes, and not for your code to parse this and handle the exception.

gateway_data

Plain HashRef (i.e., not blessed) containing any extra data regarding the exception that might be useful. For example:

{
    raw_lwp_request    => $req, # $res->isa('HTTP::Request')
    raw_lwp_response   => $res, # $res->isa('HTTP::Response')
    http_status_code   => 400,
    error_code         => 'XM-231',
    message            => 'That currency is currently not supported',
    context            => 'currency',
    exception_id       => 'e171eadad51791966aad6ac10bb6d16354d1952',
}

That HashRef is supposed to be non-standard, as a way of keeping information that is only relevant to certain gateways. Although some things might be standardized, such as the LWP request and response, for instance. Again, this is still being designed.

DISCLAIMER

This is very EXPERIMENTAL. We're still designing the interface, and the error codes are not defined yet. This role will not be usable before the documentation of all error codes.

AUTHOR

André Walker <andre@andrewalker.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by André Walker.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.