Validation Errors

Overviewanchor

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

Hierarchyanchor

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.

  1. Callback
  2. Promise
gateway.customer.create({
  email: "invalidEmail",
  creditCard: {
    number: "notNumeric",
    billingAddress: {
      countryName: "notAValidCountry"
    }
  }
}, (err, result) => { });

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 levelsanchor

To get the errors on all levels, you can iterate over result.errors.deepErrors(). deepErrors() returns an array of hashes representing the errors.

  1. Callback
  2. Promise
gateway.customer.create({
 // ...
}, (err, result) => {
  const deepErrors = result.errors.deepErrors();

  for (const i in deepErrors) {
    if (deepErrors.hasOwnProperty(i)) {
      console.log(deepErrors[i].code);
      console.log(deepErrors[i].message);
      console.log(deepErrors[i].attribute);
    }
  }
});

Errors at specific levelsanchor

To get errors at a specific level, use the for method. The attribute will indicate which attribute is invalid.

  1. Callback
  2. Promise
gateway.customer.create({
  // ...
}, (err, result) => {
  const errors = result.errors;

  const customerErrors = errors.for("customer").deepErrors();
  for (const i in customerErrors) {
    if (customerErrors.hasOwnProperty(i)) {
      console.log(customerErrors[i].code);
      console.log(customerErrors[i].message);
      console.log(customerErrors[i].attribute);
    }
  }

  const creditCardErrors = errors.for("customer").for("creditCard").deepErrors();
  for (const i in creditCardErrors) {
    if (creditCardErrors.hasOwnProperty(i)) {
      console.log(creditCardErrors[i].code);
      console.log(creditCardErrors[i].message);
      console.log(creditCardErrors[i].attribute);
    }
  }

  const billingAddressErrors = errors.for("customer").for("creditCard").for("billingAddress").deepErrors();
  for (const i in billingAddressErrors) {
    if (billingAddressErrors.hasOwnProperty(i)) {
      console.log(billingAddressErrors[i].code);
      console.log(billingAddressErrors[i].message);
      console.log(billingAddressErrors[i].attribute);
    }
  }
});

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

  1. Node.js
result.errors.for("customer").length;
// number of errors only on customer

result.errors.for("customer").for("creditCard").length;
// number of errors only on credit card

Errors on specific attributeanchor

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.

  1. Node.js
result.errors.for("customer").on("email");
result.errors.for("customer").for("creditCard").on("number");
result.errors.for("customer").for("creditCard").for("billingAddress").on("countryName");

Base errorsanchor

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.

  1. Callback
  2. Promise
gateway.subscription.update("theSubscriptionId", {
  price: "10.00"
}, (err, result) => {
  const baseErrors = result.errors.for("subscription").on("base");
});

Errors on add-ons/discountsanchor

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

  1. Callback
  2. Promise
gateway.subscription.create({
  paymentMethodToken: "thePaymentMethodToken",
  planId: "thePlanId",
  addOns: {
    update: [
      { existingId: "increase_10", amount: "invalid" },
      { existingId: "increase_20", quantity: -2 }
    ]
  }
}, (err, result) => {
  const error1 = result.errors.for("subscription").for("addOns").for("update").forIndex(0).on("amount");
  const error2 = result.errors.for("subscription").for("addOns").for("update").forIndex(1).on("quantity");
});

See also