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.

Java
Copy
Copied
CustomerRequest request = new CustomerRequest()
    .email("invalid_email")
    .creditCard()
        .number("not_numeric")
        .billingAddress()
            .countryName("not_a_valid_country")
            .done()
        .done();

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 getAllDeepValidationErrors on result.getErrors()

Java
Copy
Copied
for (ValidationError error : result.getErrors().getAllDeepValidationErrors()) {
    System.out.println(error.getCode());
    System.out.println(error.getMessage());
}

Errors at specific levels

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

Java
Copy
Copied
List<ValidationError> customerErrors = result.getErrors().forObject("customer").getAllValidationErrors();
for (ValidationError error : customerErrors) {
    System.out.println(error.getAttribute());
    System.out.println(error.getCode());
    System.out.println(error.getMessage());
}

List<ValidationError> creditCardErrors = result.getErrors().forObject("customer").forObject("creditCard").getAllValidationErrors();
for (ValidationError error : creditCardErrors) {
    System.out.println(error.getAttribute());
    System.out.println(error.getCode());
    System.out.println(error.getMessage());
}

List<ValidationError> addressErrors = result.getErrors().forObject("customer").forObject("creditCard").forObject("billingAddress").getAllValidationErrors();
for (ValidationError error : addressErrors) {
    System.out.println(error.getAttribute());
    System.out.println(error.getCode());
    System.out.println(error.getMessage());
}

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

Java
Copy
Copied
result.getErrors().forObject("customer").size();
//  Number of errors only on customer

result.getErrors().forObject("customer").forObject("creditCard").size();
//  Number of errors only on credit card

result.getErrors().forObject("customer").forObject("creditCard").forObject("billingAddress").size();
//  Number of errors only on billing address

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.

Java
Copy
Copied
result.getErrors().forObject("customer").onField("email");
result.getErrors().forObject("customer").forObject("creditCard").onField("number");
result.getErrors().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.

Java
Copy
Copied
SubscriptionRequest request = new SubscriptionRequest()
    .price(new BigDecimal("10.00"));

Result<Subscription> result = gateway.subscription().update("the_subscription_id", request);

for (ValidationError error : result.getErrors().forObject("subscription").onField("base")) {
    System.out.println(error.getMessage());
}

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).

Java
Copy
Copied
SubscriptionRequest request = new SubscriptionRequest()
    .paymentMethodToken("the_payment_method_token")
    .planId("the_plan_id")
    .addOns()
        .update("addon_7")
            .amount(new BigDecimal("-15"))
            .done()
        .update("discount_7")
            .quantity(-10)
            .done()
        .done();

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

List<ValidationError> amountErrors = result.getErrors().forObject("subscription").forObject("addOns").forObject("update").forIndex(0).onField("amount");
for (ValidationError error : amountErrors) {
    System.out.println(error.getMessage());
}

List<ValidationError> quantityErrors = result.getErrors().forObject("subscription").forObject("addOns").forObject("update").forIndex(1).onField("quantity");
for (ValidationError error : quantityErrors) {
    System.out.println(error.getMessage());
}

See also

Still have questions?

If you can’t find an answer, contact our Support team.