# Code and Formats source: https://developer.mastercard.com/points-activity-service/documentation/code-and-formats/index.md ## Error Handling {#error-handling} The Loyalty Points Activity Service API uses standard HTTP response codes for success and failure notifications, and our errors are further classified by error type. In general, 200 HTTP codes correspond to success, 40X codes are for the developer or user-related failures, and 50X codes are for runtime or system errors. This section contains information about the response codes and error messages that can be returned by the APIs. ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by the Loyalty Points Activity Service APIs, other error codes can be returned by the Mastercard gateway, which verifies your request's signature and routes it to the correct location. For further information about 4xx/5xx response codes returned by the gateway and their possible resolutions, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/). ## Application Error Codes {#application-error-codes} ### Error Structure {#error-structure} 4xx/5xx error response messages have the following format (the Error array may contain multiple error items): ```json { "Errors": { "Error": [ { "Source": "", "Description": "", "Recoverable": "true/false", "Details": "null" } ] } } ``` | Field | Description | |-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Source** | The application (rewards-points-api) generates this error. Every error message that is generated and returned by the gateway will have this field equal to Gateway. When the value of the source field is something else, it means the error was generated elsewhere. For example, the rewards-points-api. | | **ReasonCode** | A unique constant identifying the error case encountered when the Loyalty Points Activity Service API is called. For example, INVALID_INPUT, ACCOUNT_NOT_FOUND | | **Description** | Description of the `ReasonCode` field with additional details. | | **Recoverable** | Indicates whether this error will always be returned for this request, or retrying could change the outcome. For example, if the request contains an invalid request parameter, retrying will never result in success. However, if the error is related to some unexpected timeout with the service, retrying the call could result in a successful response. | | **Details** | Provide detailed error information wherever appropriate to help in resolving errors. | ## HTTP Response Codes {#http-response-codes} | HTTP Response Code | Description | |-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **200 OK** | The request was completed successfully. | | **400 BAD REQUEST** | General error when the request could not be fulfilled due to errors such as validation errors, or missing required data. | | **401 UNAUTHORIZED** | Error code response for missing or invalid authentication token. (for example, A client with a clientId does not have access) | | **404 NOT FOUND** | The requested resource is not found. | | **500 INTERNAL SERVER ERROR** | The server encountered an unexpected condition that prevented it from fulfilling the request. It indicates an error that the caller cannot address from their end. Requests resulting in a 500 response code will generally include the Loyalty Points Activity Service API Errors structure in the response. | ## Loyalty Points Activity Service Error Codes {#loyalty-points-activity-service-error-codes} ### POST /points-adjustments {#post---points-adjustments} | Reason Code | Description | |--------------------------------|--------------------------------------------------------------------------------------------------| | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | PROGRAM_MAPPING_ERROR | Configuration error. The enterprise site is not found. | | SITE_PROGRAM_MAPPING_ERROR | Configuration error. The program is not mapped to the enterprise site. | | UNAUTHORIZED | A client with a clientId does not have access. | | ACCOUNT_NOT_FOUND | Account is not found. | | USER_NOT_FOUND | User is not found. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | | ADJUSTED_BY_USER_NOT_FOUND | The adjustment by the user is not valid. Send a valid user ID. | | ADJUSTMENT_TYPE_CODE_NOT_VALID | Adjustment type code not found or too many records found for adjustment code. | | ADJUSTMENT_FAILED | Unable to perform the adjustment. Look into the Details field and reach out to the support team. | ### GET /points-adjustments-details {#get---points-adjustments-details} | Reason Code | Description | |----------------------------|--------------------------------------------------------------------------------------------------| | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | PROGRAM_MAPPING_ERROR | Configuration error. The enterprise site is not found. | | SITE_PROGRAM_MAPPING_ERROR | Configuration error. The program is not mapped to the enterprise site. | | UNAUTHORIZED | A client with a clientId does not have access. | | ACCOUNT_NOT_FOUND | An account is not found. | | USER_NOT_FOUND | User is not found. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | | INVALID_LANGUAGE | Invalid language code. | | INVALID_HOUSEHOLD | Invalid Household ID. | | ADJUSTMENT_DETAILS_FAILED | Unable to get adjustment details. Look into the Details field and reach out to the support team. | ### GET /points-details {#get---points-details} | Reason Code | Description | |----------------------------|--------------------------------------------------------------------------------------------------| | ACCOUNT_NOT_FOUND | An account is not found. | | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | | PROGRAM_MAPPING_ERROR | Configuration error. The enterprise site is not found. | | SITE_PROGRAM_MAPPING_ERROR | Configuration error. The program is not mapped to the enterprise site. | | UNAUTHORIZED | A client with a clientId does not have access. | | USER_NOT_FOUND | User is not found. | ### POST /points-details-searches {#post---points-details-searches} | Reason Code | Description | |----------------------------|--------------------------------------------------------------------------------------------------| | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | ENCRYPTION_ERROR | The request body is not encrypted. | | DECRYPTION_ERROR | Failed to decrypt the request body. | | PROGRAM_MAPPING_ERROR | Configuration error. The enterprise site is not found. | | SITE_PROGRAM_MAPPING_ERROR | Configuration error. The program is not mapped to the enterprise site. | | UNAUTHORIZED | A client with a clientId does not have access. | | ACCOUNT_NOT_FOUND | An account is not found. | | USER_NOT_FOUND | User is not found. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | ### GET /points-expirations-details {#get---points-expirations-details} | Reason Code | Description | |----------------------------|--------------------------------------------------------------------------------------------------| | USER_NOT_FOUND | User is not found. | | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | | SITE_PROGRAM_MAPPING_ERROR | Configuration error. The program is not mapped to the enterprise site. | | PROGRAM_MAPPING_ERROR | Configuration error. The enterprise site is not found. | | ACCOUNT_NOT_FOUND | An account is not found. | | UNAUTHORIZED | A client with a clientId does not have access. | ### POST /points-transfers {#post---points-transfers} | Reason Code | Description | |------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | PROGRAM_MAPPING_ERROR | Configuration error. The enterprise site is not found. | | SITE_PROGRAM_MAPPING_ERROR | Configuration error. The program is not mapped to the enterprise site. | | UNAUTHORIZED | A client with a clientId does not have access. | | ACCOUNT_NOT_FOUND | An account is not found. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | | TRANSFER_ACCOUNT_NOT_ENROLLED | The Transfer account details do not match our records. Make sure the account is enrolled. | | TRANSFER_ACCOUNT_NOT_GOOD_STANDING | The donating account must be in Good Standing to perform point transfers. | | RECEIVE_ACCOUNT_NOT_ENROLLED | The Receiving account details do not match our records. Make sure the account is enrolled. | | RECEIVE_ACCOUNT_INACTIVE | The receiving account must be in Good Standing to perform point transfers. | | MISMATCHED_PARENT_ICA | Recipient you designate to receive your transferred points must be a customer of the same bank. | | SAME_HOUSEHOLD_TRANSFER_RECEIVE_ACCOUNTS | The recipient account is in the originating Account Group. You cannot transfer points to the same account Group. | | INVALID_TRANSFER_QTY | Invalid Transfer Quantity. Transfer Quantity cannot be less than zero. | | NOT_ENOUGH_PTS_TO_TRANSFER | Transfer Account has insufficient points to meet the request. | | SAME_TRANSFER_RECEIVE_ACCOUNTS | You cannot transfer points to the same account number. | | RECEIVE_ACCOUNT_LOST_STOLEN | Receiving account is Lost or Stolen. | | INCOMPATIBLE_PROGRAMS | Transfer and Receiving account programs are not compatible. | | POINT_TRANSFER_MIN_POINTS_CAP_EXCEEDED | The points transfer quantity cannot be less than the minimum points available for transfer. | | POINT_TRANSFER_MAX_POINTS_CAP_EXCEEDED | The points transfer quantity cannot be more than the maximum points available for transfer. | | POINT_TRANSFER_MONTHLY_CAP_EXCEEDED | Amount of points exceeds the monthly cap. | | POINT_TRANSFER_YEARLY_CAP_EXCEEDED | Amount of points exceeds the yearly cap. | | NO_AVAILABLE_POINTS | The transfer card has no available points. | | TRANSFER_FAILED | Unable to perform points transfer. Look into the Details field and reach out to the [support](https://developer.mastercard.com/points-activity-service/documentation/support/index.md#get-help/) team. | ## Resolution Tips {#resolution-tips} Use this section to resolve a reason code returned by the Loyalty Points Activity Service. Work through the steps in order. The `Recoverable` field in the error response tells you whether retrying the same request can succeed. When `Recoverable` is `false`, correct the request or the account configuration first, because retrying the identical call returns the same error. ### Request and validation errors {#request-and-validation-errors} | Reason Code | Where it occurs | Resolution tips | |------------------------|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_INPUT | All operations | 1. Read the `Description` element to identify the invalid field. 2. Compare that field against the schema in the [API Reference](https://developer.mastercard.com/points-activity-service/documentation/api-reference/index.md). 3. Correct the value and retry. | | MISSING_REQUIRED_FIELD | All operations | 1. Read the `Description` element to identify the missing field. 2. Add the field to your request. 3. Retry. For `GET /points-details` and `GET /points-expirations-details`, confirm you sent both `user_id` and `user_id_type`. | | INVALID_LANGUAGE | `GET /points-adjustments-details` | 1. Replace `language` with a 5-character code configured for your program, such as `en_US`. 2. Retry. Omit the parameter to default to English. | | INVALID_HOUSEHOLD | `GET /points-adjustments-details` | 1. Confirm `household_id` belongs to the same program as the user. 2. Retry with the corrected value. | ### Identity and access errors {#identity-and-access-errors} | Reason Code | Where it occurs | Resolution tips | |----------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | UNAUTHORIZED | All operations | 1. Confirm your project has access to the Loyalty Points Activity Service. 2. Confirm you are using the keys issued for the environment you are calling, because Sandbox and Production keys differ. 3. Rebuild the authorization header as described in [Client Authentication](https://developer.mastercard.com/points-activity-service/documentation/api-basics/index.md#client-authentication) and retry. | | ACCOUNT_NOT_FOUND | All operations | 1. Verify the account identifier is correct. 2. Confirm the account is enrolled in the Rewards program. 3. Retry with a valid identifier. | | USER_NOT_FOUND | All operations | 1. Verify `user_id` is correct. 2. Confirm `user_id_type` matches the identifier you sent, either `RANAC` or `RANCU`. 3. Retry. | | ADJUSTED_BY_USER_NOT_FOUND | `POST /points-adjustments` | 1. Send a valid user ID in the `adjustedBy` field. 2. Retry. | ### Encryption errors {#encryption-errors} | Reason Code | Where it occurs | Resolution tips | |------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ENCRYPTION_ERROR | `POST /points-details-searches`, `POST /points-adjustments`, `POST /points-transfers` | 1. Encrypt the request body before sending it, as described in [Encryption](https://developer.mastercard.com/points-activity-service/documentation/api-basics/index.md#encryption). 2. Confirm your client uses the Mastercard client encryption library. 3. Retry. | | DECRYPTION_ERROR | `POST /points-details-searches`, `POST /points-adjustments`, `POST /points-transfers` | 1. Confirm you encrypted with the current encryption key for the environment you are calling. 2. Download the key again from your project dashboard if it was rotated. 3. Retry. | ### Configuration errors {#configuration-errors} These indicate a program setup issue that you cannot correct in the request. Retrying returns the same error. | Reason Code | Where it occurs | Resolution tips | |--------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | PROGRAM_MAPPING_ERROR | All operations | Contact your Mastercard representative with your Consumer Key and the failing request so the enterprise site mapping can be corrected. If you do not have a representative, use [Get Help](https://developer.mastercard.com/points-activity-service/documentation/support/index.md#get-help). | | SITE_PROGRAM_MAPPING_ERROR | All operations | Contact your Mastercard representative so the program can be mapped to the enterprise site. If you do not have a representative, use [Get Help](https://developer.mastercard.com/points-activity-service/documentation/support/index.md#get-help). | | ADJUSTMENT_TYPE_CODE_NOT_VALID | `POST /points-adjustments` | 1. Use an adjustment type code configured for your program. 2. Ask your Mastercard representative for the configured list if the code is rejected. 3. Retry. | | INCOMPATIBLE_PROGRAMS | `POST /points-transfers` | Transfer only between accounts in compatible programs. Contact your Mastercard representative to confirm which programs are compatible. | ### Points transfer errors {#points-transfer-errors} | Reason Code | Where it occurs | Resolution tips | |------------------------------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------| | TRANSFER_ACCOUNT_NOT_ENROLLED | `POST /points-transfers` | 1. Confirm the sending account details match the enrolled account. 2. Enroll the account if needed. 3. Retry. | | RECEIVE_ACCOUNT_NOT_ENROLLED | `POST /points-transfers` | 1. Confirm the receiving account details match the enrolled account. 2. Enroll the account if needed. 3. Retry. | | TRANSFER_ACCOUNT_NOT_GOOD_STANDING | `POST /points-transfers` | The donating account must be in Good Standing. Resolve the account status with the issuer, then retry. | | RECEIVE_ACCOUNT_INACTIVE | `POST /points-transfers` | The receiving account must be in Good Standing. Resolve the account status with the issuer, then retry. | | RECEIVE_ACCOUNT_LOST_STOLEN | `POST /points-transfers` | Send the transfer to a different account, because the receiving account is reported Lost or Stolen. | | MISMATCHED_PARENT_ICA | `POST /points-transfers` | Choose a recipient who is a customer of the same bank, then retry. | | SAME_TRANSFER_RECEIVE_ACCOUNTS | `POST /points-transfers` | Choose a different recipient account number, because points cannot be transferred to the same account. | | SAME_HOUSEHOLD_TRANSFER_RECEIVE_ACCOUNTS | `POST /points-transfers` | Choose a recipient outside the originating Account Group, then retry. | | INVALID_TRANSFER_QTY | `POST /points-transfers` | Send a transfer quantity greater than zero, then retry. | | NOT_ENOUGH_PTS_TO_TRANSFER | `POST /points-transfers` | 1. Check the current balance with `GET /points-details`. 2. Reduce the transfer quantity to the available balance. 3. Retry. | | NO_AVAILABLE_POINTS | `POST /points-transfers` | Confirm the transfer card balance with `GET /points-details`. Transfer only after points are available. | | POINT_TRANSFER_MIN_POINTS_CAP_EXCEEDED | `POST /points-transfers` | Increase the quantity to at least the program minimum, then retry. | | POINT_TRANSFER_MAX_POINTS_CAP_EXCEEDED | `POST /points-transfers` | Reduce the quantity to the program maximum, then retry. | | POINT_TRANSFER_MONTHLY_CAP_EXCEEDED | `POST /points-transfers` | The monthly cap is reached. Retry in the next calendar month or ask your Mastercard representative about the configured cap. | | POINT_TRANSFER_YEARLY_CAP_EXCEEDED | `POST /points-transfers` | The yearly cap is reached. Retry in the next calendar year or ask your Mastercard representative about the configured cap. | ### Processing failures {#processing-failures} Retrying does not resolve these errors on its own. | Reason Code | Where it occurs | Resolution tips | |---------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ADJUSTMENT_FAILED | `POST /points-adjustments` | 1. Capture the `Details` field from the response. 2. Contact the [support](https://developer.mastercard.com/points-activity-service/documentation/support/index.md#get-help) team with the `Details` value and the request you sent. | | ADJUSTMENT_DETAILS_FAILED | `GET /points-adjustments-details` | 1. Capture the `Details` field from the response. 2. Contact the [support](https://developer.mastercard.com/points-activity-service/documentation/support/index.md#get-help) team with the `Details` value and the request you sent. | | TRANSFER_FAILED | `POST /points-transfers` | 1. Capture the `Details` field from the response. 2. Confirm no points moved by checking both balances with `GET /points-details`. 3. Contact the [support](https://developer.mastercard.com/points-activity-service/documentation/support/index.md#get-help) team with the `Details` value. | ### Next steps {#next-steps} * Reproduce and confirm error handling with the negative path cases in the [Testing](https://developer.mastercard.com/points-activity-service/documentation/tutorials-and-guides/api-testing-tutorial/index.md) tutorial. * Review the scenario for each operation in [Use Cases](https://developer.mastercard.com/points-activity-service/documentation/use-cases/index.md).