Validation Errors

Overview

Validation errors will be returned on error result objects when we can't process the API call because parameters are invalid. Validation errors contain the following:

code - for programmatic consumption
message - for human consumption
attribute - the parameter that caused an error

Hierarchy

Errors are returned in a hierarchy that matches the parameter hierarchy. For example, when creating a customer with a credit card and billing address, the credit card is nested under customer, and the billing address under credit card.

Ruby

result = gateway.customer.create({
    :email => "invalid_email",
    :credit_card => {
        :number => "not_numeric",
        :billing_address => {
            :country_name => "not_a_valid_country"
        }
    }
})

You can get errors at all levels, errors at a specific level, or errors at a specific level on a specific attribute.

All errors on all levels

To get the errors on _all levels_, call each on `result.errors`. You can also check `result.errors.size` for the number of total errors.

Ruby

result.errors.each do |error| 
    puts error.code
    puts error.message
end

Errors at specific levels

To get errors at a _specific level_, use the `for` method. The `attribute` will indicate which attribute is invalid.

Ruby

result.errors.for(:customer).each do |error| 
    puts error.attribute
    puts error.code
    puts error.message
end
result.errors.for(:customer).for(:credit_card).each do |error| 
    puts error.attribute
    puts error.code
    puts error.message
end
result.errors.for(:customer).for(:credit_card).for(:billing_address).each do |error| 
    puts error.attribute
    puts error.code
    puts error.message
end

From a _specific level_, you can also get the number of errors at that level using `size`.

Ruby

# number of errors on customer
result.errors.for(:customer).size

# number of errors on credit card
result.errors.for(:customer).for(:credit_card).size

# number of errors on billing address
result.errors.for(:customer).for(:credit_card).for(:billing_address).size

Errors on specific attribute

You can also get errors at a specific level on a specific attribute. This is useful if you want to display error messages inline in your forms.

ruby

result.errors.for(:customer).on(:email)
result.errors.for(:customer).for(:credit_card).on(:number)
result.errors.for(:customer).for(:credit_card).for(:billing_address).on(:country_name)

Base errors

Sometimes validation errors aren't caused by a specific input parameter. For example, canceled subscriptions can't be updated. For these validation errors, we use an attribute named "base" for the validation error.

Ruby

result = gateway.subscription.update(
    "the_subscription_id",
    :price => "10.00"
);

result.errors.for(:subscription).on(:base).each do |error| 
    puts error.message
end

Errors on add-ons/discounts

It is possible to add, update and remove many add-ons and discounts at once. If any of the add-ons or discounts contain errors, these errors will be indexed based on the order of the add-on or discount in the request (beginning at 0).

Ruby

result = gateway.subscription.create({
    :payment_method_token => "the_payment_method_token",
    :plan_id => "the_plan_id",
    :add_ons => {
        :update => [
            {
                :existing_id => "add_on_id_1",
                :amount => "invalid"
            },
            {
                :existing_id => "add_on_id_2",
                :quantity => -10
            }
        ]
    }
});

result.errors.for(:subscription).for(:add_ons).for(:update).for_index(0).on(:amount).each do |error| 
    puts error.message
end
result.errors.for(:subscription).for(:add_ons).for(:update).for_index(1).on(:quantity).each do |error| 
    puts error.message
end

Validation Errors

Overview

Hierarchy

All errors on all levels

Errors at specific levels

Errors on specific attribute

Base errors

Errors on add-ons/discounts

See Also