# Code and Formats source: https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md ## Error Codes {#error-codes} The error message returned will depend on which API has generated the error and at what part of the consumer journey the request fails. Error messages are categorized as: **Gateway Error Messages** : Returned by the API gateway and mostly thrown when OAUTH authentication fails. **API Error Messages**: Returned by the API and thrown for any technical or business decline by Mastercard. Note: To ensure forward-compatibility, client implementations must be resilient to add new elements to the API responses in the future. ## Gateway Error Messages {#gateway-error-messages} All the errors that the gateway returns follow the same data format: *HTTP status code 4xx/5xx* ### Error Structure {#error-structure} ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` ### Field Overview: {#field-overview} * **Source**: The application that generated this error. Every error message that the gateway generates and returns, have this field equal to Gateway. When the value of the source field is something else, it means that the error was generated elsewhere. * **ReasonCode**: A unique constant identifying the error case encountered during transaction processing. For example, INVALID_SIGNATURE is used when the request signature does not match the expected one. * **Description**: Description of the ReasonCode field with more 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 signature, 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**: Always null, present for backward compatibility. Note: For more information on gateway error messages including the error codes, refer to [Gateway Error Codes](https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md#gateway-error-codes). ### Gateway Error Codes {#gateway-error-codes} In addition to service error codes, error codes can also be returned by Mastercard's gateway, which is used to verify your request's signature, and route it to the correct location. You can find a list of the errors returned by our gateway, as well as resolutions to each at [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/). ## HTTP Response codes/Reason codes {#http-response-codesreason-codes} Resource requests use HTTP response codes to provide a coarse-grain indication of the result of each request. The most common expected response codes for the supported HTTP methods are as follows: | **Code** | **Response** | **Description** | |----------|------------------------|---------------------------------------------------------------------------------------------------------------------------| | 200 | (OK) | The request was completed successfully. | | 201 | (CREATED) | Successful creation occurred using a POST request. The Location header will contain a link to the newly created resource. | | 202 | (ACCEPTED) | The request has been accepted for processing, but the processing has not been completed. | | 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) | Missing or invalid authentication token. | | 403 | (FORBIDDEN) | The user is not authorized to perform the operation. | | 404 | (NOT FOUND) | The requested resource was not found. | | 405 | (METHOD NOT ALLOWED) | The requested URL exists, but the requested HTTP method is not applicable. | | 406 | (NOT ACCEPTABLE) | This response code is returned when a user enters anything except application/json, in the Accept header. | | 415 | (INVALID CONTENT TYPE) | This response code is returned when a user enters anything except application/json, in the Content-Type header. | ## API Error Messages {#api-error-messages} | **Name** | **Description** | **Errors** | |---------------|--------------------------------------------------------------|------------------| | Error Wrapper | The error response object, which gets returned in any error. | Errors{...} | | Errors | Error object, which returns a list of error objects. | ErrorList\[...\] | | **Name** | **Description** | |-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Description | Error object, which contains details about the error. | | Source | string minLength: 1 maxLength: 100 example: customer-data-api The application name that generated this error. | | Reason Code | String minLength: 1 maxLength: 100 Example: invalid.request.parameter A unique constant identifying the error case encountered during request processing. | | Description | String minLength: 10 maxLength: 1000 Example: One of the request parameters is invalid. Try again with the correct request Short description of the ReasonCode field. | | Recoverable | Boolean Example: false Indicates whether this error will always be returned for this request, or retrying. | | Details | String minLength: 0 maxLength: 5000 Example: paymentCardId size must be between 36 and 36 Optional) Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors. | ## Merchant Participation API Error Codes {#merchant-participation-api-error-codes} Note: The following error codes are specific to the Merchant Participation API. For errors with the Source field value as Gateway, refer to [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/). For a complete list of Merchant Participation API-specific error codes, refer to the following table. | Reason Code | Description | Tip to Resolve | |------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `invalid.request.parameter` | Missing or invalid request parameters. | * The Offset index must be a valid Integer value. * The Limit must be a valid integer value. * Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response, update the request parameters | | `invalid data: ` | If any missing or invalid parameter is passed within the request payload, the `` in the error message contains the exact parameter, which is passed incorrectly. **Example** , If the `acquirerICA` validation fails while processing then, reason code - invalid data: `acquirerICA` is displayed. Probable `` values will be like - `merchantLegalName`, `countryCode`, `acquirerICA`, `merchantGroup`, `optIn`, wallets, address, and so on. | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the request parameters. | | `forbidden` | Forbidden to access the resource. | Your account is inactive, kindly contact your Mastercard associate to get the approval. | | `not.acceptable.header` | Accept header value is not application/json | Verify and correct the Accept header value and try again. | | `internal.server.error` | There was a downstream issue when processing the request. | Contact MCI Support. | | `invalid.data` | Missing or invalid data within the request payload. | Review payload request against [API technical specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis). Verify that the request is valid as per the API Reference and based on the description provided in the response, update the request body fields. | | `invalid.data.input` | Missing required parameters MAID or MAID type. | Ensure that MAID or MAID type are present in the market type 3 and 2 merchant. | | `invalid.request.parameter` | Missing or invalid request parameters. | Review the payload request against the [API technical specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis). Verify that the request is valid as per the API Reference and based on the description provided in the response, update the request parameters. | | `account.not.registered` | We cannot find the account, which you are using to access this service. | Register your account or contact your Mastercard associate, if you have already registered with us earlier. Your account onboarding is not yet completed, kindly onboard your project. | | `unauthorized` | Unauthorized to access the resource. | Authentication is required and has failed or has not been provided. | ## Installments Approvals API Error Codes {#installments-approvals-api-error-codes} | Reason Code | Description | Tip to Resolve | |----------------------------------|-----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `invalid.request.body.parameter` | Field format or type is invalid | Verify that the request is valid as per [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the request parameters. | | `unauthenticated` | Authentication is failed. The client must authenticate to get the requested response. | Authentication is required and has failed or has not been provided. | | `forbidden` | Your account is not approved to access the API or resource, kindly contact your Mastercard associate to get approval. | Your account is inactive, kindly contact your Mastercard associate to get approval. | | `not.acceptable.header` | Accept header value is not application/json | Verify and correct the Accept header value and try again. | | `not.found` | Resource is not found. | Contact MCI Support | ## Installments Offers APIs Error Codes {#installments-offers-apis-error-codes} | Reason Code | Description | Tip to Resolve | |--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `invalid.request.parameter` | 1. Country Code Not Supported 2. Currency Code Not Supported 3. Invalid Currency Code 4. Invalid Country and Currency Pair 5. Email and mobile are empty. Either Email Or Mobile must exist 6. Merchant object is empty. Country code and MCC must exist 7. Transaction Amount is not in Range 8. Transaction Date is not in Range 9. The PAN provided is invalid 10. Amount is invalid 11. Currency is invalid 12. A country code must be present 13. `AquirerId`, `MerchantId`, and `CountryCode` must be present 14. Local Transaction date and time must be present 15. Decryption key not found 16. Request header x-openapi-clientid is missing in the request 17. Merchant name is invalid 18. One of the following combination of data must be present: 1. If the requester passes either of acquirer ID or merchant ID then country, acquirer ID and merchant ID is mandatory 2. In merchant name - country code is mandatory 3. In URL - country code is mandatory 19. Start Date Must be Future Date 20. Product Code Cannot be Updated 21. Provider ID Cannot be updated 22. Country Code Cannot be updated 23. Currency Code Cannot be Updated 24. Currency Symbol Cannot be updated 25. Start Date is not in Range 26. End Date is not in Range 27. End Date less than Start Date or less than Current Date 28. The minimum purchase amount must be equal or greater than Fifty 29. SPP offers must be having this configuration - number of installments=4, interest rate=0, frequency=BIWEEKLY and fees=0 30. Offer is not for the US 31. Product Code Not Supported for List of merchants for bilateral offers. 32. Product Code Not Supported for List of MCC Exclusion for offers 33. For Product Code ETA to ETG a list of bilateral merchants must be present for the offer 34. The maximum purchase amount should be a numeric value without decimal 35. The minimum purchase amount should be numeric value without decimals 36. Maximum purchase amount is not in range 37. Minimum purchase amount is not in range 38. Minimum purchase amount should be less than maximum purchase amount | Verify that the request is valid as per [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the request parameters. | | `transaction.amount.not.match` | Provided the transaction amount does not match with the offer | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the amount request parameters. | | `transaction.date.not.match` | Provided the transaction date does not match with offer | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the transaction date request parameters. | | `pan.not.match` | Provided PAN does not match with offer | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the PAN request parameters. | | `country.not.match` | Country does not match with provided `offerID` | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the country request parameters. | | `invalid data: ` | Description for the error | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the request parameters. | | `unauthorized` | Unauthorized to access the resource. | Authentication is required and has failed or has not been provided. | | `forbidden` | Forbidden to access the resource. | Your account is inactive. Kindly contact your Mastercard associate to get the approval. | | `not.found` | URI/Resource not found. OR Resource {`offerId`} not found. | Contact MCI Support `OfferId` not found. Please try again with valid/Active `offerId` value. | | `not.active` | Resource {`offerId`} not active. | `offerId` not active. Please try again with valid/Active `offerId` value. | | `invalid.accept.header` | Accept header should be application/json. | Verify and correct the Accept header value and try again. | | `invalid.content.type` | Content-Type header should be application/json. | Verify and correct the Content-Type header value and try again. | ## Installments Plans API Error Codes {#installments-plans-api-error-codes} | Reason Code | Description | Tip to Resolve | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `unauthorized` | Unauthorized to access the resource | Authentication is required and has failed or has not been provided | | `not.found` | URI/Resource not found. OR Resource {`clientId`} not found. | Contact MCI Support `clientId` not found. Please try again with valid/Active `clientId` value | | `invalid.request.parameter` | 1. `TransactionAmountMisMatch` 2. `TransactionDateMisMatch` 3. `InvalidTransactionCurrency` 4. `BlankPAN` 5. `NonNumericPAN` 6. `InvalidPANLength` 7. `InvalidTokenPAN` 8. `PANMisMatch` 9. `InvalidLengthMerchantURL` 10. `InvalidMerchantURL` 11. `InvalidAcquirerId` 12. `InvalidLengthAcquirerId` 13. `InvalidCountryCode` 14. `InvalidLengthMcc` 15. `InvalidLengthMerchantId` 16. `InvalidMerchantId` 17. `InvalidAmountType` 18. `InvalidLengthSTAN` 19. `NonNumericSTAN` 20. `InvalidLengthRNN` 21. `NonNumericRRN` 22. `InvalidLengthAuthCode` 23. `NonNumericAuthCode` 24. `InvalidTransactionLinkId` 25. `InvalidTransmissionDate Time` 26. `InvalidLocalTransactionDate Time` 27. `InvalidFrequency` 28. `InvalidPresentedOffersDSP` 29. `InvalidPresentedOffersDRNG` | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis), and based on the description provided in the response update the request parameters | | `forbidden` | Your account does not have access to the API or resource | Your account is inactive. Kindly contact your Mastercard associate to get the approval | ## PAN List API Error Codes {#pan-list-api-error-codes} | Reason Code | Description | Tip to Resolve | |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `internal.server.error` | There was a downstream issue when processing the request | Please contact MCI Support | | `invalid.accountRange` | The account range in the request is invalid. 1. Account range not valid 2. Invalid account range for pan list | Please ensure that the account range you have entered is valid. * Account range not valid (for creating a new PAN list). Please enter a valid account range * Invalid account range for PAN list (for the existing PAN list). Please enter the correct account range for the existing PAN list | | `invalid.data` | Missing or invalid data within the request payload. Review payload request against API technical specification. 1. (panListName) must not be null or empty 2. (PANs) must not be null or empty 3. (`panListName`) must match " \^ \[a-zA-Z0-9\\\\s-\]{1,64}$\\ 4. (`panListId`) must match " \^ \[0-9\]{18}$" 5. (Either PANs or Account Range) must not be null or empty 6. (accountRange.accountRangeLow) must match " \^ \[0-9\]{11,19}$\\ 7. (accountRange.accountRangeHigh) must match " \^ \[0-9\]{11,19}$\\" 8. PANs' size exceeded the limit of \< max register limit \> 9. Your account is not associated with any customer. Kindly contact your Mastercard associate to get approval. | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) and based on the description provided in the response update the request body fields. * If `accountRange` is not provided, PANs must be provided * If PANs are not provided, `accountRange` must be provided * The number of PANs to register must not exceed the max limit for a registration request * If `panListId` is not provided, then the request is an update PAN list request and `panListName` must be provided. | | `invalid.pan` | The request to update a PAN list does not have any valid PANs | Please ensure that there is at least one valid PAN in the request | | `invalid.request.parameter` | Missing or invalid request parameters. Review payload request against API technical specification. 1. Your account is not associated with any customer. Kindly contact your Mastercard associate to get approval. 2. PAN list not found for ID \< `panListId` \> | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) and based on the description provided in the response update the request parameters. | | `forbidden` | Forbidden to access the resource | Your account is inactive. Kindly contact your Mastercard associate to get the approval | | `unauthorized` | Unauthorized to access the resource | Authentication is required and has failed or has not been provided |