Validation Errors

Vaildation errors will be returned on error result objects when we cannot process the API call because parameters are invalid. Validation errors have a code, message, and attribute. The code is intended for programmatic consumption, the message is human-readable, and the attribute identified which parameter the validation error is on.

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.

var request = new CustomerRequest
{
    Email = "invalid_email",
    CreditCard = new CreditCardRequest
    {
        Number = "not_numeric",
        BillingAddress = new CreditCardAddressRequest
        {
            CountryName = "not_a_valid_country"
        }
    }
};

You can get all 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 all errors on all levels, call DeepAll on result.Errors. 

foreach (ValidationError error in result.Errors.DeepAll()) {
    Console.WriteLine(error.Code);
    Console.WriteLine(error.Message);
}

Errors at Specific Levels

Note: Prior to version 2.6.0, arguments to the ForObject method must be delimited by - and arguments to the OnField method must be delimited by _. For example, ForObject("billing-address") and OnField("country_name").

In versions 2.6.0 and later, we accept any casing.

To get errors at a specific level, use the ForObject method to narrow the scope. Then, call All() to retrieve the list of ValidationError objects. The Attribute will indicate which attribute is invalid.

var customerErrors = result.Errors.ForObject("Customer");
foreach (ValidationError error in customerErrors.All()) {
    Console.WriteLine(error.Attribute);
    Console.WriteLine(error.Code);
    Console.WriteLine(error.Message);
}

var creditCardErrors = customerErrors.ForObject("CreditCard");
foreach (ValidationError error in creditCardErrors.All()) {
    Console.WriteLine(error.Attribute);
    Console.WriteLine(error.Code);
    Console.WriteLine(error.Message);
}

var billingAddressErrors = creditCardErrors.ForObject("BillingAddress");
foreach (ValidationError error in billingAddressErrors.All()) {
    Console.WriteLine(error.Attribute);
    Console.WriteLine(error.Code);
    Console.WriteLine(error.Message);
}

From a specific level, you can also get the number of errors at that level using the Count property.

// number of errors on customer
result.Errors.ForObject("Customer").Count;

// number of errors on credit card
result.Errors.ForObject("Customer").
              ForObject("CreditCard").Count;

// number of errors on billing address
result.Errors.ForObject("Customer").
              ForObject("CreditCard").
              ForObject("BillingAddress").Count;

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.

result.Errors.ForObject("Customer").
              OnField("Email");

result.Errors.ForObject("Customer").
              ForObject("CreditCard").
              OnField("Number");

result.Errors.ForObject("Customer").
              ForObject("CreditCard").
              ForObject("BillingAddress").
              OnField("CountryName");

Base Errors

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

var result = gateway.Subscription.Update(
  "the_subscription_id",
  new SubscriptionRequest { Price = 10.00M }
);

var errors = result.Errors.ForObject("Subscription").OnField("Base");
foreach (var error in errors) {
    Console.WriteLine(error.Message);
}

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 (begining at 0).

SubscriptionRequest request = new SubscriptionRequest
{
    PaymentMethodToken = "the_payment_method_token",
    PlanId = "the_plan_id",
    AddOns = new AddOnsRequest
    {
        Update = new UpdateAddOnRequest[]
        {
            new UpdateAddOnRequest
            {
                ExistingId = "increase_10",
                Amount = -200M
            },
            new UpdateAddOnRequest
            {
                ExistingId = "increase_20",
                Quantity = -9
            }
        }
    }
};

Result<Subscription> result = gateway.Subscription.Create(request);

List<ValidationError> amountErrors = result.Errors.ForObject("Subscription").ForObject("AddOns").ForObject("Update").ForIndex(0).OnField("Amount");

foreach (ValidationError error in amountErrors) {
    Console.WriteLine(error.Message);
}

List<ValidationError> quantityErrors = result.Errors.ForObject("Subscription").ForObject("AddOns").ForObject("Update").ForIndex(1).OnField("Quantity");

foreach (ValidationError error in quantityErrors) {
    Console.WriteLine(error.Message);
}

See Also