# 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: [HTTP Status Codes/Reason Codes](https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md#http-status-codesreason-codes): The most common expected response codes for the supported HTTP methods. [Gateway Error Messages](https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md#gateway-error-messages): Returned by the API gateway and mostly thrown when OAUTH authentication fails. [API Error Messages](https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md#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 tolerate new elements that may be added to API responses in the future. ## HTTP Status Codes/Reason Codes {#http-status-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. | HTTP status code | Reason Code | Response Description | Resolution Tips | |--------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | 200 (OK) | N/A | The request was completed successfully. | No action needed - request processed successfully. | | 201 (CREATED) | N/A | Successful creation occurred using a POST request. The Location header will contain a link to the newly-created resource. | No action needed - resource created successfully. Check Location header for new resource URL. | | 204 (NO CONTENT) | N/A | The server successfully processed the request and is not returning any content. | No action needed - resource updated/deleted successfully. | | 400 (BAD REQUEST) | BAD_REQUEST | General error when the request could not be fulfilled due to errors such as validation errors or missing required data. | Validate request parameters, check required fields, and ensure proper data formats before retrying. | | 401 (UNAUTHORIZED) | UNAUTHORIZED | Missing or invalid authentication token. | Verify authentication credentials, refresh tokens if expired, and ensure proper authorization headers are included. | | 403 (FORBIDDEN) | PERMISSION_DENIED | The user has insufficient permissions to a resource or action. | Contact administrator to verify user permissions or use an account with appropriate access rights. | | 404 (NOT FOUND) | NOT_FOUND | The requested resource was not found. | Verify the resource URL/ID is correct and the resource exists. Check for typos in the endpoint path. | ## 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} To ensure a consistent experience across all Mastercard APIs, the following structure is followed by the Mastercard Installments API for each error scenario that can occur. #### Single Error {#single-error} * JSON ```JSON { "Errors": { "Error": [ { "source": "", "recoverable": "e.g. true/false", "details": "For further clarification, please contact the Product Operations team at installments.product.support@mastercard.com" } ] } } ``` #### Multiple Errors {#multiple-errors} * JSON ```JSON { "Errors": { "Error": [ { "Source": "merchant-participation-api", "ReasonCode": "invalid data: mids[0]", "Description": "Example Mid Merchant 01 at index 0 for field mids[0] value '8754127452026701111111111111111111111111111111111111111111' must match ^[A-Za-z0-9]{1,15}$", "Recoverable": false, "Details": "" }, { "Source": "merchant-participation-api", "ReasonCode": "invalid data: optIn", "Description": "Example Mid Merchant 01 at index 0 for field optIn value 'I' must match \"^(?:Y|N)$\"", "Recoverable": false, "Details": "" }, { "Source": "merchant-participation-api", "ReasonCode": "invalid data: duns", "Description": "Example Mid Merchant 01 at index 0 for field duns value '879847426000000000000000000000000' size must be between 1 and 9", "Recoverable": false, "Details": "" }, { "Source": "merchant-participation-api", "ReasonCode": "invalid data: wallets[0].walletId", "Description": "Example Mid Merchant 01 at index 0 for field wallets[0].walletId value '0' must be greater than or equal to 1", "Recoverable": false, "Details": "" }, { "Source": "merchant-participation-api", "ReasonCode": "invalid data: maidType", "Description": "Example Maid Merchant 02 at index 1 for field maidType - Please include MAID type", "Recoverable": false, "Details": "" }, { "Source": "merchant-participation-api", "ReasonCode": "invalid data: wallets[1].walletAcceptance", "Description": "Example Maid Merchant 02 at index 1 for field wallets[1].walletAcceptance value 'O' must match \"^(?:Y|N)$\"", "Recoverable": false, "Details": "" } ] } } ``` ### Field Overview: {#field-overview} * **Source**: The application that generates this error. Every error message that the gateway generates has this field set to Gateway. When the source field has any other value, 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/). ## 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 whether retrying could change the outcome. | | 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](https://developer.mastercard.com/unified-installments/documentation/testing/mastercard-installments-program-with-merchant-participation/merchant-participation-api-positivesc/index.md)-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/mastercard-installments-services/inbound-api/index.md#apis), and based on the description provided in the response, update the request parameters | | `invalid data: ` | If a parameter in the request payload is missing or invalid, `` in the error message identifies that parameter. For example, if `acquirerICA` validation fails, the reason code is `invalid data: acquirerICA`. Possible `` values include `merchantLegalName`, `countryCode`, `acquirerICA`, `merchantGroup`, `optIn`, `wallets`, and `address`. | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/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. 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. | | `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/mastercard-installments-services/inbound-api/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 the MAID and MAID type are present for market type 2 and market type 3 merchants. | | `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/mastercard-installments-services/inbound-api/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 that you are using to access this service. | Register your account. If you have already registered, your account onboarding is not complete. Complete onboarding for your project, or contact your Mastercard associate. | | `unauthorized` | Unauthorized to access the resource. | Authentication is required and has failed or has not been provided. | ## Installments Offers APIs Error Codes {#installments-offers-apis-error-codes} For a complete list of [Installments Offers API](https://developer.mastercard.com/unified-installments/documentation/testing/mastercard-installments-payment-services/installments-offers-api/index.md)-specific error codes, refer to the following table. | 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. `AcquirerId`, `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/mastercard-installments-services/inbound-api/index.md#apis), and based on the description provided in the response update the request parameters. | | `transaction.amount.not.match` | The transaction amount does not match the offer. | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/index.md#apis), and based on the description provided in the response update the amount request parameters. | | `transaction.date.not.match` | The transaction date does not match the offer. | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/index.md#apis), and based on the description provided in the response update the transaction date request parameters. | | `pan.not.match` | The PAN does not match the offer. | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/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/mastercard-installments-services/inbound-api/index.md#apis), and based on the description provided in the response update the country request parameters. | | `invalid data: ` | A request parameter is missing or invalid. `` identifies the parameter. | Verify that the request is valid as per the [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/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. Contact your Mastercard associate to get 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} For a complete list of [Installments Plans API](https://developer.mastercard.com/unified-installments/documentation/testing/mastercard-installments-payment-services/installments-plan-api/index.md)-specific error codes, refer to the following table. | 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/mastercard-installments-services/inbound-api/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. Contact your Mastercard associate to get approval | ## PAN List API Error Codes {#pan-list-api-error-codes} For a complete list of [PAN List API](https://developer.mastercard.com/unified-installments/documentation/testing/mastercard-installments-payment-services/pan-list-api/index.md)-specific error codes, refer to the following table. | 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/mastercard-installments-services/inbound-api/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/mastercard-installments-services/inbound-api/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. Contact your Mastercard associate to get approval | | `unauthorized` | Unauthorized to access the resource | Authentication is required and has failed or has not been provided |