...

Overview

If an error occurs when calling any of the Loyalty API endpoints, an error response will be returned with a standard response format (see below). Use the HTTP error code in coordination with the code field to determine the specific scenario that generated that error code, which will be listed in the corresponding endpoint documentation.

Format

RBI's loyalty API is set up to validate many different incentive and transaction related scenarios via a rules engine. As a result of trying to create a transaction via this API, one or many of these validations could fail, and resulting errors may be returned in the API response. These errors will follow a consistent structure when returned. Please find an example of that structure below:.

Error Structure

The error response will have a top level code property set to RulesError. The details of which rules failed will live in the details.ruleEvaluation array. Each one of the objects within that array will contain the following properties that can be interpretted:

• code <string>: this will always be set to RulesError, when the error comes from the loyalty engine.

• details object that explains more information about the error(s).

• ruleEvaluation array of objects that each specify error(s) found in the request.

  • code <string>: descriptive error code, used to differentiate error scenarios that return the same HTTP status code.

  • ruleId <string>: the ID of the rule that failed / caused an error.

  • message <string>: human readable error message, in English. These are not designed for use in direct customer display.

  • currentValue <string> (optional): The value provided in the request that was used to evaluate the rule (if applicable).

  • targetValue <array> (optional): The expected value(s) used to evaluate the currentValue (if applicable). In the example below, a storeId of 12345 was provided in the transaction (this is the currentValue), but the incentive provided was set to restrict this offer redemption to only stores with ids 1234 or 2345 (the array in the targetValue).

  • incentiveId <string> (optional): The ID of the incentive (offer or reward) related to the rule failure (if applicable).

Example Response

{
    "code": "RulesError",
    "details": {
        "ruleEvaluation": [
            {
 modes",           "code": "invalid-service-mode",
            "currentValue": "TAKEOUT",
            "message": "Service mode is not in the list of valid
            "ruleId": "service-mode",
            "targetValue": [
              "EAT_IN"
              ],
            "incentiveId": "3e9a71a8-75f8-493a-bb2a-e13f92052427"
             },
    {
            "code": "invalid-store-id",
            "currentValue": "12345",
            "message": "Store is not in the list of valid stores",
            "ruleId": "store-restrictions",
            "targetValue": [
              "1234",
              "2345"
            ],
            "incentiveId": "88a13d3f-e5af-4a23-8b32-3ed421662c62"
    }
],
"isEngineError": true,
"errorConfig": {
    "transitional": {
        "silentJSONParsing": true,
        "forcedJSONParsing": true,
        "clarifyTimeoutError": false
    },
    "transformRequest": [
      null
    ],
    "transformResponse": [
      null
    ],
    "timeout": 0,
    "xsrfCookieName": "XSRF-TOKEN",
    "xsrfHeaderName": "X-XSRF-TOKEN",
    "maxContentLength": -1,
    "maxBodyLength": -1,
    "headers": {
          "Accept": "application/json, text/plain, */*",
          "Content-Type": "application/json",
          "x-api-key": "************************************HyaM",
          "x-region": "US",
          "x-request-id": "cla8q5fzx000e36i03wsmhejq",
          "User-Agent": "axios/0.26.1",
          "Content-Length": 1397
            },
      "method": "post",
      "data": "__REDACTED__",
      "url": "{{url}}"
      } 
  },
  "message": "Rule evaluation failed"
}

... as you can see, the error response will have a top level code property set to RulesError. The details of which rules failed will live in the details.ruleEvaluation array. Each one of the objects within that array will contain the following properties that can be interpretted:

• code: The error code representing the particular rule failure

• ruleId: The id of the rule that failed

• currentValue: The value provided in the request that was used to evaluate the rule (if applicable)

• targetValue: The expected value(s) used to evaluate the currentValue (if applicable). In the example above, a storeId of 12345 was provided in the transaction (this is the currentValue), but the incentive provided was set to restrict this offer redemption to only stores with ids 1234 or 2345 (the array in the targetValue).

• message: A full english description of the rule failure. These are not designed for use in direct customer display

• incentiveId: The id of the incentive related to the rule failure (if applicable)

List of possible errors

Common Errors

Please find the list of all possible errors below. You will find each one's particular code, ruleId, and message.

Subtotal Below Minimum Spend

• code: below-minimum-spend

• ruleId: minimum-spend

• message: Invalid Incentive Object Provided. Purchase did not meet minimum spend configuration.

Incentive Exceeds Limit per Order

• code: exceeds-limit-per-order

• ruleId: limit-per-order

• message: Limit per order exceeded

Incentive Max Redemption

• code: exceeds-max-redemption

• ruleId: max-redemption

• message: `Invalid Incentive Object Provided. Max redemptions limit reached

Insufficient Point Balance

• code: insufficient-point-balance

• ruleId: point-balance

• message: User does not have sufficient funds to redeem reward

Invalid Day of the week

• code: invalid-day-of-the-week

• ruleId: day-of-the-week

• message: Promotion was not redeemed on a valid weekday

Invalid End Date

• code: invalid-end-date

• ruleId: date-span

• message: Invalid Incentive Object Provided. Does not fall within end date parameters

Invalid Start Date

• code: invalid-start-date

• ruleId: date-span

• message: Invalid Incentive Object Provided. Does not fall within starrt date parameters

Invalid Enrollment Start Date

• code: invalid-enrollment-start-date

• ruleId: user-enrollment

• message: Invalid Incentive Object Provided. Does not fall within user enrollment start date

Invalid Enrollment End Date

• code: invalid-enrollment-end-date

• ruleId: user-enrollment

• message: Invalid Incentive Object Provided. Does not fall within user enrollment end date

Invalid Payment Method

• code: invalid-payment-method

• ruleId: payment-method

• message: Selected payment method is not one of the accepted methods.

Invalid Redemption Type Combination

• code: invalid-redemption-type-combination

• ruleId: max-redemption-types

• message: Invalid combination of offer redemption types. (Standard|Surprise|Swap) offers exceed limit.

• notes: Note the "(Standard|Surprise|Swap)" in the message above. the actual rendered message will reflect only one of the offer types within that list.

Invalid Scope

• code: invalid-scope

• ruleId: incentive-scope

• message: Invalid Incentive Object Provided. Incentive of this type can not be used.

Invalid Service Mode

• code: invalid-service-mode

• ruleId: service-mode

• message: Service mode is not in the list of valid modes

Invalid Stacking

• code: invalid-stacking

• ruleId: is-stackable

• message: Invalid Incentive Object Provided. Offer can not be stacked on top of other offers.

Invalid Store Id

• code: invalid-store-id

• ruleId: store-restrictions

• message: Store is in the list of invalid stores

Invalid Swaps

• code: invalid-swaps

• ruleId: swaps

• message: Invalid Offer Provided. Swaps does not match

User not logged in

• code: missing-user

• ruleId: first-order

• message: User must be logged in to see this incentive

Not user's first order

• code: not-first-order

• ruleId: first-order

• message: User has existing claimed transactions

Not user's birthday

• code: not-user-birthday

• ruleId: user-birthday

• message: Birthday did not span within duration

Invalid Quest Activation Date

• code: quest-past-activation-date

• ruleId: must-activate-by

• message: Invalid Quest Activation date. Current date is past mustActivateBy parameter

Unsatisfied Cart Requirements

• code: unsatisfied-cart-requirements

• ruleId: cart-requirement

• message: At least one of the required entries was not satisfied

Unsatisfied Cart Requirements Exclusion

• code: unsatisfied-cart-requirements-exclusion

• ruleId: cart-requirement

• message: At least one of the excluded entries was not satisfied

User is Within the Cooldown Period

• code: within-cool-down-period

• ruleId: cool-down

• message: Invalid Incentive Object Provided. Cool down not reached yet.