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.

Java

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

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

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

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

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

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

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());
}

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