Customer Errors

When performing customer-related operations such as registration, login, or profile updates, the API returns specific error types that help you handle different validation and business logic failures. This guide explains each error type and how to handle them.

Overview

Customer operations return errors through the userErrors field in their respective payloads. Each error is a UserError interface implementation that provides:

• message: A human-readable error description
• path: The field path where the error occurred (e.g., ["updateCustomer", "password"])
• type-specific fields: Additional context depending on the error type

Where Customer Errors Appear

Customer errors can be returned from the following mutations:

• registerCustomer - When creating a new customer account
• updateCustomer - When updating customer profile or password
• resetPassword - When resetting a forgotten password
• login - When authenticating a customer

Password Validation Errors

Password validation errors occur when a customer provides a password that doesn't meet security requirements. These errors are returned from the registerCustomer, updateCustomer, and resetPassword mutations.

PasswordIsTooShort

Returned when the password is shorter than the minimum required length.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred
• minPasswordLength: Int! - The minimum required password length

Example:

{
  "message": "A password must be at least 8 characters long",
  "path": ["registerCustomer", "password"],
  "minPasswordLength": 8
}

PasswordIsTooLong

Returned when the password exceeds the maximum allowed length.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred
• maxPasswordLength: Int! - The maximum allowed password length

Example:

{
  "message": "A password must be at most 128 characters long",
  "path": ["updateCustomer", "password"],
  "maxPasswordLength": 128
}

PasswordIsLeaked

Returned when the password appears in known data breach databases. This is a security measure to prevent customers from using compromised passwords.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred
• occurrences: Int! - Number of times this password has appeared in breach databases

Example:

{
  "message": "This password is known to be insecure, it appears on the lists of leaked passwords at least 5 times",
  "path": ["registerCustomer", "password"],
  "occurrences": 5
}

PasswordRequiresLowercaseLetter

Returned when the password doesn't contain at least one lowercase letter.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred

Example:

{
  "message": "A password must contain at least one lowercase letter",
  "path": ["updateCustomer", "password"]
}

PasswordRequiresUppercaseLetter

Returned when the password doesn't contain at least one uppercase letter.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred

Example:

{
  "message": "A password must contain at least one uppercase letter",
  "path": ["registerCustomer", "password"]
}

PasswordRequiresNumber

Returned when the password doesn't contain at least one numeric digit.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred

Example:

{
  "message": "A password must contain at least one number",
  "path": ["updateCustomer", "password"]
}

PasswordRequiresSymbol

Returned when the password doesn't contain at least one special character (symbol).

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred

Example:

{
  "message": "A password must contain at least one symbol",
  "path": ["registerCustomer", "password"]
}

PasswordCannotStartOrEndWithWhitespace

Returned when the password starts or ends with whitespace characters (spaces, tabs, etc.).

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred

Example:

{
  "message": "A password cannot start or end with a whitespace character",
  "path": ["updateCustomer", "password"]
}

PasswordCannotContainNewline

Returned when the password contains newline characters.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred

Example:

{
  "message": "A password cannot contain a new line",
  "path": ["registerCustomer", "password"]
}

Authentication Errors

PasswordNeedsChange

Returned when a customer attempts to log in but their password has expired or needs to be changed for security reasons. This error is only returned from the login mutation.

Fields:

• message: String! - The error message
• path: [String!]! - Field path where the error occurred
• resetID: String! - Token to use for password reset
• resetI: String! - Additional token for password reset verification

Example:

{
  "message": "Your password needs to be changed",
  "path": ["login"],
  "resetID": "abc123def456",
  "resetI": "xyz789"
}

What to do next (resetPassword)

When you receive PasswordNeedsChange, prompt the customer to set a new password and call the resetPassword mutation using the values returned in the error:

• Use resetID as the id argument
• Use resetI as the i argument

Example:

mutation {
  resetPassword(
    password: "password"
    confirmPassword: "password"
    id: "1" # from PasswordNeedsChange.resetID
    i: "a264ed08d12da8ed905d5685116f5720" # from PasswordNeedsChange.resetI
    loginOnSuccess: true
  ) {
    userErrors {
      __typename
      message
      path
      ... on PasswordIsTooShort {
        minPasswordLength
      }
      ... on PasswordIsTooLong {
        maxPasswordLength
      }
      ... on PasswordIsLeaked {
        occurrences
      }
    }
  }
}

Query examples

Below are focused GraphQL snippets that demonstrate how userErrors can be queried for common customer flows. These are illustrative and highlight error handling rather than full payloads.

Registration (registerCustomer)

Handles userErrors during registration:

mutation RegisterCustomer($input: CustomerRegisterInput!) {
  registerCustomer(input: $input) {
    loggedIn {
      id
      email
      firstName
    }
    userErrors {
      __typename
      message
      path
      ... on PasswordIsTooShort {
        minPasswordLength
      }
      ... on PasswordIsTooLong {
        maxPasswordLength
      }
      ... on PasswordIsLeaked {
        occurrences
      }
    }
  }
}

Login (PasswordNeedsChange)

Below is a minimal example focusing on how userErrors may include PasswordNeedsChange during login:

mutation Login($email: String!, $password: String!) {
  login(email: $email, password: $password) {
    userErrors {
      message
      path
      ... on PasswordNeedsChange {
        resetId
        resetI
      }
    }
  }
}

Error Types by Mutation

A quick reference showing which mutations can return each error type:

Error type	registerCustomer	updateCustomer	resetPassword	login
PasswordIsTooShort	✓	✓	✓
PasswordIsTooLong	✓	✓	✓
PasswordIsLeaked	✓	✓	✓
PasswordRequiresLowercaseLetter	✓	✓	✓
PasswordRequiresUppercaseLetter	✓	✓	✓
PasswordRequiresNumber	✓	✓	✓
PasswordRequiresSymbol	✓	✓	✓
PasswordCannotStartOrEndWithWhitespace	✓	✓	✓
PasswordCannotContainNewline	✓	✓	✓
PasswordNeedsChange				✓