# Code and Formats source: https://developer.mastercard.com/easy-savings-specials/documentation/code-and-formats/index.md ## Error structure {#error-structure} To ensure a consistent experience across all Mastercard APIs, the Easy Savings Specials Merchant Offers API implements the following structure for each error scenario that may occur. | Field | Description | |-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Source | This field indicates the application that generated the error. Every error message that the Gateway generates and returns has this field set to `Gateway`. If the field value is `EasySavingsSpecialsOffers`, the Easy Savings Specials Merchant Offers application generates the error. | | ReasonCode | The Easy Savings Specials Merchant Offers API identifies the error case encountered using a unique constant. For example, the system returns **BAD REQUEST** when the user fails to provide the necessary required parameter. | | Description | The `ReasonCode` field provides a description of the specific reason for the error. It includes additional details to help identify the cause of the issue and assist in troubleshooting. | | Recoverable | This field indicates whether the system always returns the error for this request or if retrying the request changes the outcome. For example, if the request contains an invalid parameter, retrying never results in success. However, if the error is due to an unexpected timeout with the service, retrying the call may result in a successful response. | | Details | Provide detailed error information wherever applicable to assist in resolving issues effectively. | Here are sample responses: ##### NULL PARAMETER {#null-parameter} ```json { "Errors": { "Error": [ { "Source": "EasySavingsSpecialsOffers" "ReasonCode": "NULL_BIN" "Description": "BIN parameter must not be null or empty" "Recoverable": false, "Details":"BIN parameter is not passed correctly." } ] } } ``` ##### DATA NOT FOUND {#data-not-found} ```json { "Errors": { "Error": [ { "Source": "EasySavingsSpecialsOffers" "ReasonCode": "COUNTRY_NOT_FOUND", "Description": "Provided country is either incorrect or is not supported for this program" "Recoverable": false, "Details": "Country code should be a three-lettered ISO code" } ] } } ``` ## Response overview {#response-overview} Resource requests use HTTP response codes to provide a general indication of the result of each request. The most common response codes expected for the supported HTTP methods are: | **Status Code** | **Response** | **Description** | |-----------------|-------------------------|-----------------------------------------------------------------------------------------------| | 200 | `OK` | Everything is functioning as expected. | | 400 | `BAD REQUEST` | The request was unacceptable, typically due to a missing required parameter. | | 404 | `NOT FOUND` | The requested resource does not exist. | | 405 | `NOT ALLOWED` | The server does not support the requested HTTP method. | | 500 | `INTERNAL SERVER ERROR` | The server encountered an unexpected condition that prevented it from completing the request. | ## HTTP Response codes/Reason codes {#http-response-codesreason-codes} Resource requests use HTTP response codes to provide an indication of the result of each request. The most common expected response codes for the supported HTTP methods are: | **Response Code** | **Reason Code** | **Description** | **Recoverable** | **Details** | **How to resolve** | |-------------------|--------------------------|------------------------------------------------------------------------------|-----------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | `NULL_BIN` | The BIN parameter must not be null or empty. | NO | The BIN parameter was not passed correctly. | Provide a valid 8-digit Mastercard Business Cardholder's BIN in the request. | | 400 | `INVALID_BIN` | The BIN provided does not conform to the expected Mastercard format. | NO | An invalid 8-digit Mastercard Business BIN has been provided. | Provide a valid 8-digit Mastercard Business Cardholder's BIN in the request. | | 400 | `NULL_COUNTRY` | The country parameter must not be null or empty. | NO | The country code should be a three-letter ISO code. | Provide the country code in the three-letter ISO code format, as specified in the [ISO 3166 country codes](https://www.iso.org/iso-3166-country-codes.html) for supported countries. Use the Countries API to retrieve the valid list of country codes. | | 400 | `INVALID_COUNTRY` | Provide a valid ISO country code. | NO | The country code should be a three-letter ISO code. | Provide the country code in the three-letter ISO code format, as specified in the [ISO 3166 country codes](https://www.iso.org/iso-3166-country-codes.html) for supported countries. Use the Countries API to retrieve the valid list of country codes. | | 400 | `NULL_LANGUAGE` | The language parameter must not be null or empty. | NO | The language code must follow the IETF BCP format. | Provide the language code in the IETF BCP format, as specified in [BCP 47](https://www.rfc-editor.org/info/bcp47#appendix-A), for supported languages only. Use the Countries API to retrieve an updated list of valid supported languages. | | 400 | `INVALID_LANGUAGE` | Provide a valid IETF BCP language code. | NO | The language code must follow the IETF BCP format. | Provide the language code in the IETF BCP format, as specified in [BCP 47](https://www.rfc-editor.org/info/bcp47#appendix-A), for supported languages only. Use the Countries API to retrieve an updated list of valid supported languages. | | 400 | `NULL_OFFER_ID` | The `Offer_ID` parameter must not be null or empty. | NO | The `Offer_ID` parameter is the unique identifier of the offer. | Provide the `Offer_ID` parameter associated with the offer to fetch the voucher code. | | 400 | `NULL_OFFERS_ARRAY` | The offers array must not be null or empty. | NO | The offers array was not passed correctly. | The Offers array must be passed correctly with the `Offer_ID` parameter to complete the request. | | 400 | `NULL_ORDER_ID` | The `Order_ID` parameter must not be null. | NO | The `Order_ID` parameter is the unique identifier of the previously generated order. | Provide the `Order_ID` parameter associated with the order to fetch the order details and associated voucher codes. | | 400 | `INVALID_LIMIT` | The limit value is invalid. It must be a positive integer. | NO | The limit is an optional parameter with a default value of 30. | Ensure that the limit value is an integer greater than or equal to 1. This is an optional parameter and defaults to 30 if not provided. | | 400 | `INVALID_OFFSET` | The offset value is invalid. It must be a non-negative integer. | NO | Offset is an optional parameter with a default value of 0. | Ensure that the offset value is an integer greater than or equal to 0. This is an optional parameter and defaults to 0 if not provided. | | 404 | `BIN_NOT_FOUND` | The provided BIN is either incorrect or not registered for this program. | NO | Selected BINs have been associated with the relevant offers. | Provide a valid BIN associated with the Easy Savings Specials Merchant Offers program. | | 404 | `COUNTRY_NOT_FOUND` | The provided country is either incorrect or not supported for this program. | NO | The country code should be a three-letter ISO code. | Provide the country code in the three-letter ISO code format, as specified in [ISO 3166 country codes](https://www.iso.org/iso-3166-country-codes.html), for supported countries. Refer to the supported countries list in the [Support](https://developer.mastercard.com/easy-savings-specials/documentation/support/index.md) section. | | 404 | `LANGUAGE_NOT_FOUND` | The provided language is either incorrect or not supported for this program. | NO | The list of supported languages is updated regularly. | Provide the language code in the IETF BCP format, as specified in [BCP 47](https://www.rfc-editor.org/info/bcp47#appendix-A), for supported languages only. Use the Countries API to retrieve an updated list of valid supported languages. | | 404 | `OFFER_ID_NOT_FOUND` | The `Offer_ID` parameter is either incorrect or has expired. | NO | The offers list and corresponding `Offer_ID` parameter are updated regularly. | Retry by passing the correct `Offer_ID` parameter or update the offers list to retrieve the latest offers. | | 404 | `ORDER_ID_NOT_FOUND` | The `Order_ID` parameter is either incorrect or has expired. | NO | The `Order_ID` parameter is the unique identifier of the previously generated order. | Verify the `Order_ID` parameter and retry by providing a valid `Order_ID` parameter. | | 405 | `METHOD_NOT_ALLOWED` | The HTTP method is not allowed for the requested URL. | NO | HTTP methods are used to perform actions on target resources. | Rectify the HTTP method for the target resource. To learn more, refer to the [Parameters](https://developer.mastercard.com/easy-savings-specials/documentation/parameters/index.md) section. | | 500 | `INTERNAL_SERVER_ERROR ` | An unexpected internal error occurred in the application. | YES | The request might be incomplete. Retry after some time. | Retry the request in a few minutes or contact our support team for assistance. | ### Gateway error codes {#gateway-error-codes} In addition to error codes returned by the Easy Savings Specials Merchant Offers API, Mastercard Gateway also returns error codes. It verifies your request signature and routes it to the correct location. To learn more about the 4xx response codes returned by the gateway and their possible resolutions, refer to [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/errors-troubleshooting/gateway-error-codes/).