Stripe.Error (stripity_stripe v2.17.2) View Source

A struct which represents an error which occurred during a Stripe API call.

This struct is designed to provide all the information needed to effectively log and maybe respond to an error.

It contains the following fields:

  • :source – this is one of
    • :internal – the error occurred within the library. This is usually caused by an unexpected or missing parameter.
    • :network – the error occurred while making the network request (i.e. :hackney.request/5 returned an error.) In this case, :code will always be :network_error. The :hackney_reason field in the :extra map contains the actual error reason received from hackney.
    • :stripe – an error response was received from Stripe.
  • :code – an atom indicating the particular error. See "Error Codes" for more detail.
  • :request_id – if :source is :stripe, this will contain the request ID for logging and troubleshooting. Otherwise, this field is nil.
  • :message – a loggable message describing the error. This should not be shown to your users but is intended for logging and troubleshooting.
  • :user_message – if Stripe has provided a user-facing message (e.g. when a card is declined), this field will contain it. Otherwise it is nil.
  • :extra - a map which may contain some additional information about the error. See "Extra Fields" for details.

Extra Fields

The :extra field contains a map of miscellaneous information about the error which may be useful. The fields are not present if not relevant. The possible fields are:

  • :card_code – when :code is :card_error, contains one of Stripe's decline reasons.
  • :decline_code – an optional short string provided by the bank when a card is declined.
  • :param – for errors where a particular parameter was the cause, indicates which parameter was invalid.
  • :charge_id – when a Charge was declined, indicates the ID of the failed Charge which was created.
  • :http_status – for :stripe errors, the HTTP status returned with the error.
  • :raw_error – the raw error map received from Stripe.
  • :hackney_reason – for :network errors, contains the error reason received from hackney.

Error Codes

The :code fields may be one of the following:

  • :api_connection_error, :api_error, :authentication_error, :card_error, :invalid_request_error, :rate_limit_error, :validation_error – as per the Stripe docs
  • :bad_request, :unauthorized, :request_failed, :not_found, :conflict, :too_many_requests, :server_error, :unknown_error – these only occur if Stripe did not send an explicit type for the error. They have the meaning as defined in Stripe's HTTP status code summary
  • :network_code – used only when :source is :network. Indicates an error occurred while making the request.
  • :valid_keys_failed, :required_keys_failed, :endpoint_fun_invalid_result, :invalid_endpoint – used when :source is :internal. See Stripe.Request for details.

Link to this section Summary

Link to this section Types

Specs

card_error_code() ::
  :invalid_number
  | :invalid_expiry_month
  | :invalid_expiry_year
  | :invalid_cvc
  | :invalid_swipe_data
  | :incorrect_number
  | :expired_card
  | :incorrect_cvc
  | :incorrect_zip
  | :card_declined
  | :missing
  | :processing_error
  | :bank_account_verification_failed

Specs

error_source() :: :internal | :network | :stripe

Specs

error_status() ::
  :bad_request
  | :unauthorized
  | :request_failed
  | :not_found
  | :conflict
  | :too_many_requests
  | :server_error
  | :unknown_error

Specs

stripe_error_type() ::
  :api_connection_error
  | :api_error
  | :authentication_error
  | :card_error
  | :invalid_request_error
  | :rate_limit_error
  | :validation_error

Specs

t() :: %Stripe.Error{
  code:
    error_status()
    | stripe_error_type()
    | Stripe.Request.error_code()
    | :network_error,
  extra: %{
    optional(:card_code) => card_error_code(),
    optional(:decline_code) => String.t(),
    optional(:param) => atom(),
    optional(:charge_id) => Stripe.id(),
    optional(:http_status) => 400..599,
    optional(:raw_error) => map(),
    optional(:hackney_reason) => any()
  },
  message: String.t(),
  request_id: String.t() | nil,
  source: error_source(),
  user_message: String.t() | nil
}