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 consumptionmessage
- for human consumptionattribute
- 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.
- C#
var request = new CustomerRequest
{
Email = "invalid_email",
CreditCard = new CreditCardRequest
{
Number = "not_numeric",
BillingAddress = new CreditCardAddressRequest
{
CountryName = "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 errors on all levels, call DeepAll
on result.Errors
- C#
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.
- C#
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.
- C#
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.
- C#
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 can't be updated. For these validation errors, we use an attribute named "base" for the validation error.
- C#
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 (beginning at 0).
- C#
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);
}