Loyalty API v1 - Error Responses
Contents
- 1 Overview
- 2 Format
- 2.1 Error Structure
- 2.2 Example Response
- 3 Rule Evaluation Errors
- 3.1 Subtotal or Total Below Minimum Spend
- 3.2 Incentive Exceeds Limit per Order
- 3.3 Incentive Max Redemption
- 3.4 Insufficient Point Balance
- 3.5 Invalid Day of the week
- 3.6 Invalid End Date
- 3.7 Invalid Start Date
- 3.8 Invalid Enrollment Start Date
- 3.9 Invalid Enrollment End Date
- 3.10 Invalid Payment Method
- 3.11 Invalid Scope
- 3.12 Invalid Service Mode
- 3.13 Invalid Store Id
- 3.14 User not logged in
- 3.15 Not user's first order
- 3.16 Not user's birthday
- 3.17 Invalid Quest Activation Date
- 3.18 Unsatisfied Cart Requirements
- 3.19 Unsatisfied Cart Requirements Exclusion
- 3.20 User is Within the Cooldown Period
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.
Note that all error messages are returned in English.
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.
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 interpreted:
statusCode
<integer>: the HTTP error code returned with the response.isEngineError
<boolean>: indicates whether the error was generated by the Loyalty Engine.code
<string>: this will always be set toRulesError
, 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, for example, “store-restrictions
“.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).isEngineError
<boolean>: indicated whether the error was detected by the Loyalty Engine. For internal RBI use.
errorCode
<string> (optional): legacy error code, always “ERR_BAD_REQUEST” and can be ignored.errorConfig
<object>: contains details about the error for internal RBI use.
Example Response
{
"code": "RulesError",
"details": {
"ruleEvaluation": [
{
"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}}"
}
}
}
Rule Evaluation Errors
The most typical error returned by the Loyalty API is related to offer or reward evaluation rules. This section lists all possible rule evaluation errors that can be returned.
Subtotal or Total Below Minimum Spend
The basket subtotal or total is below the minimum spend required for at least one offer contained in the basket.
code: below-minimum-spend
ruleId: minimum-spend
message: Invalid Incentive Object Provided. Purchase did not meet minimum spend configuration.
When this validation error is received a hint should show up at the POS or Kiosk that instructs the guest to add more products to the cart to be able to redeem this offer/reward.
Incentive Exceeds Limit per Order
The offer or reward limit that can be placed in one order is exeeded.
code: exceeds-limit-per-order
ruleId: limit-per-order
message: Limit per order exceeded
When this validation error is received, this offer/reward should be removed and voided from the cart at the Kiosk or POS.
Incentive Max Redemption
The maximum redemption limit that was set for this offer or reward was reached.
code: exceeds-max-redemption
ruleId: max-redemption
message: Invalid Incentive Object Provided. Max redemptions limit reached
Insufficient Point Balance
The user does not have enough loyalty points to redeem reward.
code: insufficient-point-balance
ruleId: point-balance
message: User does not have sufficient funds to redeem reward
Invalid Day of the week
The offer or reward was not redeemed on a valid week day.
code: invalid-day-of-the-week
ruleId: day-of-the-week
message: Promotion was not redeemed on a valid weekday
Invalid End Date
The end date configured in the offer or reward is invalid, compared to current date.
code: invalid-end-date
ruleId: date-span
message: Invalid Incentive Object Provided. Does not fall within end date parameters
Invalid Start Date
The start date configured in the offer or reward is invalid, compared to current date.
code: invalid-start-date
ruleId: date-span
message: Invalid Incentive Object Provided. Does not fall within starrt date parameters
Invalid Enrollment Start Date
User enrollment start date into the loyalty program is invalid.
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
User enrollment end date into the loyalty program is invalid.
code: invalid-enrollment-end-date
ruleId: user-enrollment
message: Invalid Incentive Object Provided. Does not fall within user enrollment end date
Invalid Payment Method
The selected payment method is not one of the accepted methods.
code: invalid-payment-method
ruleId: payment-method
message: Selected payment method is not one of the accepted methods.
Invalid Scope
Offer or reward cannot be used.
code: invalid-scope
ruleId: incentive-scope
message: Invalid Incentive Object Provided. Incentive of this type can not be used.
Invalid Service Mode
Service mode is not in the list of valid service modes for the offer or reward.
code: invalid-service-mode
ruleId: service-mode
message: Service mode is not in the list of valid modes
Invalid Store Id
Restaurant number is in the list of invalid restaurants that this offer or reward can be redeemed on.
code: invalid-store-id
ruleId: store-restrictions
message: Store is in the list of invalid stores
User not logged in
User must be signed in to see this offer.
code: missing-user
ruleId: first-order
message: User must be logged in to see this incentive
Not user's first order
User must redeem this offer or reward in its first order.
code: not-first-order
ruleId: first-order
message: User has existing claimed transactions
Not user's birthday
User can only redeem offer or reward in its birthday.
code: not-user-birthday
ruleId: user-birthday
message: Birthday did not span within duration
Invalid Quest Activation Date
Quest (e.g. Invitation code on signup) start or end date is invalid.
code: quest-past-activation-date
ruleId: must-activate-by
message: Invalid Quest Activation date. Current date is past mustActivateBy parameter
Unsatisfied Cart Requirements
At least one of the cart requirement products set to that offer or reward was not satisfied.
code: unsatisfied-cart-requirements
ruleId: cart-requirement
message: At least one of the required entries was not satisfied
Unsatisfied Cart Requirements Exclusion
At least one of the excluded cart requirement products set to that offer or reward was not satisfied.
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
Offer cooldown period was not reached yet.
code: within-cool-down-period
ruleId: cool-down
message: Invalid Incentive Object Provided. Cool down not reached yet.