# Code and Formats source: https://developer.mastercard.com/traditional-fulfillment-service/documentation/code-and-formats/index.md ## Error Handling {#error-handling} The Loyalty Traditional Fulfillment 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 Traditional Fulfillment 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 (mrs-catalog-api) that 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 mrs-catalog-api. | | **ReasonCode** | A unique constant identifying the error case encountered when the Loyalty Traditional Fulfillment Service API is called. For example, INVALID_INPUT, INVALID_CATALOG_HIERARCHY_ID, INVALID_PROGRAM. | | **Description** | Description of the `ReasonCode` field with additional details. | | **Recoverable** | Indicates whether this error will always be returned for this request, or whether 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 Traditional Fulfillment Service API Errors structure in the response. | ## Loyalty Traditional Fulfillment Service Error Codes {#loyalty-traditional-fulfillment-service-error-codes} Errors surface at three points in the integration. The Mastercard API Gateway returns authentication failures before the service runs, so confirm your signing setup first. The service returns validation failures when it checks the parameters or the order payload you submitted. The service returns downstream failures when it reaches the rewards platform but cannot complete the lookup. Use the `Recoverable` field to decide what to do next. Retry the call only when `Recoverable` is `true`. When it is `false`, correct the request before you retry. The same reason code can be returned by more than one operation, and the fix differs by context. `INVALID_PROGRAM` on `GET /catalogs` means the `program_id` is not valid for your Client ID. The same code on `GET /catalogs/{catalog_id}/items` usually means the `catalog_id` you selected belongs to a different program. `UNAUTHORIZED` on the vendor operation points to vendor entitlement rather than program entitlement. ### GET /catalogs {#get---catalogs} | Reason Code | Description | |--------------------------------|-----------------------------------------------------------------------------------------------------------| | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | INVALID_LANGUAGE | Returned for an invalid request. See the "Description" element in response for more details. | | INVALID_PRODUCT_CODE | Returned for an invalid request. See the "Description" element in response for more details. | | UNAUTHORIZED | A client with a clientId does not have access. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | | INVALID_PROGRAM | Program with programId is not found. | | REWARD_CATALOGS_DETAILS_FAILED | Unable to get reward catalogs details. Please look into the `Details` field and contact the support team. | #### Resolution Tips for GET /catalogs {#resolution-tips-for-get-catalogs} | Reason Code | Typical cause | Resolution steps | |--------------------------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | INVALID_INPUT | A parameter is present but malformed. | Read the `Description` field to identify the parameter, correct its format, and resend the request. | | INVALID_LANGUAGE | The `language` value is not configured for the program. | Omit `language` to fall back to `en_US`, or send a language code that is configured for the program. | | INVALID_PRODUCT_CODE | The `product_code` is not configured for the program. | Confirm the product code with your Mastercard representative, or omit the parameter. | | UNAUTHORIZED | The Client ID is not entitled to the service. | Confirm the CIS team registered your Client ID, confirm you signed with the key for the environment you are calling, then retry. | | MISSING_REQUIRED_FIELD | A required parameter was not sent. | Add the parameter named in the `Description` field. `program_id` is required on this operation. | | INVALID_PROGRAM | The `program_id` is not found for your Client ID. | Verify the `program_id` with your Mastercard representative and confirm it belongs to the environment you are calling. | | REWARD_CATALOGS_DETAILS_FAILED | The service reached the rewards platform but could not return catalog detail. | Read the `Details` field. If `Recoverable` is `true`, retry the call. Otherwise contact support and quote the `Details` value. | ### GET /catalogs/{catalog_id}/items {#get---catalogscatalog_iditems} | Reason Code | Description | |--------------------------------|-----------------------------------------------------------------------------------------------------------| | INVALID_INPUT | Returned for an invalid request. See the "Description" element in the response for more details. | | INVALID_LANGUAGE | Returned for an invalid request. See the "Description" element in response for more details. | | INVALID_CATALOG_HIERARCHY_ID | Returned for an invalid request. See the "Description" element in response for more details. | | INVALID_PRODUCT_CODE | Returned for an invalid request. See the "Description" element in response for more details. | | UNAUTHORIZED | A client with a clientId does not have access. | | MISSING_REQUIRED_FIELD | Returned for an invalid request. See the "Description" element in the response for more details. | | INVALID_PROGRAM | Program with programId is not found. | | INVALID_CATALOG_HIERARCHY_ID | Invalid Reward Catalog HierarchyId. | | REWARD_CATALOGS_DETAILS_FAILED | Unable to get reward catalogs details. Please look into the `Details` field and contact the support team. | #### Resolution Tips for GET /catalogs/{catalog_id}/items {#resolution-tips-for-get-catalogscatalog_iditems} | Reason Code | Typical cause | Resolution steps | |--------------------------------|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | INVALID_INPUT | A parameter is present but malformed. | Read the `Description` field to identify the parameter, correct its format, and resend the request. | | INVALID_LANGUAGE | The `language` value is not configured for the program. | Omit `language` to fall back to `en_US`, or send a language code that is configured for the program. | | INVALID_CATALOG_HIERARCHY_ID | The `catalog_id` does not exist, or it belongs to a different program. | Call `GET /catalogs` again, take an `id` where `hasRewardItems` is `true`, and use that value as `catalog_id`. | | INVALID_PRODUCT_CODE | The `product_code` is not configured for the program. | Confirm the product code with your Mastercard representative, or omit the parameter. | | UNAUTHORIZED | The Client ID is not entitled to the service. | Confirm the CIS team registered your Client ID, confirm you signed with the key for the environment you are calling, then retry. | | MISSING_REQUIRED_FIELD | A required parameter was not sent. | Add the parameter named in the `Description` field. `program_id` in the query and `catalog_id` in the path are both required. | | INVALID_PROGRAM | The `program_id` is not found, or it does not match the catalog you requested. | Confirm the `program_id` and re-select a `catalog_id` returned for that same program. | | REWARD_CATALOGS_DETAILS_FAILED | The service reached the rewards platform but could not return item detail. | Read the `Details` field. If `Recoverable` is `true`, retry the call. Otherwise contact support and quote the `Details` value. | ### POST /vendors/{vendor_id}/orders/status {#post---vendorsvendor_idordersstatus} | Reason Code | Description | |--------------|------------------------------------------------| | UNAUTHORIZED | A client with a clientId does not have access. | #### Resolution Tips for POST /vendors/{vendor_id}/orders/status {#resolution-tips-for-post-vendorsvendor_idordersstatus} | Reason Code | Typical cause | Resolution steps | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | UNAUTHORIZED | The Client ID is not entitled to the vendor order operation, or the `vendor_id` in the path does not match the credentials you signed with. | Confirm your vendor onboarding with your Mastercard representative, confirm the `vendor_id` matches the vendor your key was issued for, then retry. | | MISSING_REQUIRED_FIELD | A required field in the order status array is blank or null. | Read the `Description` field, which names the exact order and field, for example `McOrderId is blank or null`. Populate that field and resend. | A `200` response does not always mean every order was applied. The response lists each order the service could not update, with its own `status`, `errorCode`, and `description`. Correct the order entries named there and resend only those orders. For the full request and response model, see the [API Reference](https://developer.mastercard.com/traditional-fulfillment-service/documentation/api-reference/index.md).