# Code and Formats source: https://developer.mastercard.com/mastercard-processing-core/documentation/code-and-formats/index.md ## HTTP Response Codes {#http-response-codes} | **Status Code** | **Response** | **Description** | |-----------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 | OK | Everything worked as expected. | | 201 | CREATED | A `POST` method successfully created a resource. | | 204 | NO CONTENT | The server successfully executed the method but returned no response body. | | 400 | BAD REQUEST | The server cannot or will not process the request due to its invalid structure or data. | | 401 | UNAUTHORIZED | The user does not have access to the service. | | 403 | FORBIDDEN | The user is not authorized to perform the operation. | | 404 | NOT FOUND | The requested resource does not exist. | | 405 | METHOD NOT ALLOWED | The requested URL exists, but the requested HTTP method is not applicable. | | 409 | CONFLICT | The request conflicts with another request (perhaps due to using the same `Idempotency-Key`). | | 412 | PRECONDITION FAILED | The server cannot match the requested entity, often by using invalid `ETAG` in `PATCH` request. | | 415 | UNSUPPORTED MEDIA TYPE | The server does not support the request payload's media type. For the Mastercard Processing API, the `Content-Type` header must be: • `application/merge-patch+json;charset=utf-8` for `PATCH` requests • `application/json;charset=utf-8` for all other HTTP methods | | 422 | UNPROCESSABLE CONTENT | The API cannot complete the requested action, or the request action is semantically incorrect or fails business validation. | ## Error Structure {#error-structure} To provide a consistent experience across all Mastercard APIs, the Mastercard Processing API follows the standard structure for each scenario that can occur. Mastercard returns errors in the following structure: ```json { "Errors":{ "Error":[ { "Source":"", "ReasonCode":"", "Description":"", "Recoverable": true/false } ] } } ``` | **Field** | **Description** | |-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Source | The application that generated the given error. Every error message generated and returned by the gateway will have this field equal to `Gateway`. If the field value is `MASTERCARD PROCESSING`, it means that an error was generated by the Mastercard Processing application. | | ReasonCode | Identifies the error case encountered when any Mastercard Processing API is called. For example, `REQUEST_VALIDATION` is used when the request is invalid due to some missing or invalid parameters. | | Description | Description of the `ReasonCode` field with additional details. | | Recoverable | Indicates whether this error will always be returned for this request or retrying can change the outcome. For example, if the request contains an invalid request parameter, retrying will never succeed. However, if the error is related to some unexpected timeout with the service, retrying the call could result in a successful response. | ## Gateway Error Codes {#gateway-error-codes} In addition to service error codes, error codes can also be returned by Mastercard's gateway. A gateway is used to verify the request's signature and route it to the correct location. You can find a list of the errors returned by our gateway and resolutions to each on the [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/) page. ## Mastercard Processing Error Codes {#mastercard-processing-error-codes} For a complete list of Mastercard Processing application-specific error codes, refer to the following table: | **HTTP Response Status Code** | **Reason Code** | **Description** | **How to Resolve** | |-------------------------------|------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 404 | ACCOUNT_CONTRACT_DOES _NOT_EXIST | Account contract with id \ not found. | Verify and correct the `account_contract_id` value in the request, and then try again. | | 400 | ADDRESS_TYPE_ALREADY _CREATED | Address type \ is already created. | The provided `addressType` is already stored in the CMS. Verify and correct the `addressType` value in the request, and then try again. | | 400 | ADDRESS_TYPE_ALREADY _DISABLED | Address type \ is already disabled. | The provided `address type` is already disabled in the CMS. | | 404 | ADDRESS_TYPE_DOES_NOT _EXIST | Address type \ not found. | The provided `address type` is not configured in the CMS for you. Verify and correct the `address_type` value in the request, and then try again. | | 404 | CARD_CONTRACT_DOES_NOT _EXIST | Card contract with id \ not found. | Verify and correct the `card_contract_id` value in the request, and then try again. | | 400 | CARD_CONTRACT_PIN_NOT_SET | The card contract PIN is not set. | Before ordering plastic by sending a `POST` request to the `/cards/{card_contract_id}/plastics` endpoint, the PIN for the card must be set (a `POST` request sent to the `/cards/{card_contract_id}/pins` endpoint). | | 400 | CARD_CONTRACT_STATUS_IS _WRONG | Card contract with id \ in wrong status to reissue. | Verify and modify the `CardContractStatusData`, and then try again. By default, only a card contract in active status can be reissued and only in inactive status can be replaced. | | 400 | CARD_CONTRACT_STATUS_IS _WRONG | Card contract with id \ in wrong status to post transaction. | Ensure that you do not post a transaction for a card contract that is inactive. | | 400 | CARD_CONTRACT_STATUS_IS _WRONG | Card contract with id \ in wrong status to set PIN. | Ensure that you set a PIN for a card contract where `cardContract.statusCode` is `00`. | | 400 | CERTIFICATE_NOT_FOUND | Cannot find response encryption key for fingerprint \ and client ID \. | Check the Mastercard Encryption Key associated with the provided Client ID in your Mastercard Developers project to ensure it is valid and has not expired. If expired, generate a new key and reconfigure your integration accordingly. | | 404 | CLASSIFIER_CODE_DOES_NOT _EXIST | Classifier with code \ not found. | The provided `classifier code` is not configured in the CMS for you. Verify and correct the `classifier_code` value in the request, and then try again. | | 404 | CLIENT_DOES_NOT_EXIST | Client with id \ not found. | Verify and correct the `clientId` value in the request, and then try again. | | 404 | CONTRACT_DOES_NOT _EXIST | Contract with id \ not found. | Verify and correct the `contract_id` value in the request, and then try again. | | 400 | CUSTOM_DATA_TAG_DOES _NOT_EXIST | Specified tag does not exist. | The provided tag name is not stored in the CMS. Verify the tag name value in the request, and then try again. | | 400 | DUPLICATED_CBS_NUMBER | Duplicated CBS number. | The provided `cbsNumber` already exists in the CMS. Verify and correct the `cbsNumber` value in the request, and then try again. | | 400 | DUPLICATED_CLIENT_NUMBER | Duplicated client number. | The provided `clientNumber` already exists in the CMS. Verify and correct the `clientNumber` value in the request, and then try again. | | 400 | DUPLICATED_CONTRACT _NUMBER | Duplicated contract number. | The provided contract number already exists in the CMS. Verify and correct the value in the request, and then try again. | | 400 | DUPLICATED_SOCIAL_NUMBER | Duplicated social number. | The provided `socialNumber` already exists in the CMS. Verify and correct the `socialNumber` value in the request, and then try again. | | 400 | DUPLICATED_TAXPAYER _IDENTIFIER | Duplicated taxpayer identifier. | The provided `taxpayerIdentifier` already exists in the CMS. Verify and correct the `taxpayerIdentifier` value in the request, and then try again. | | 400 | DUPLICATED_X_MC_ CORRELATION_ID | The given \ header was used in the previous request. | Specify the correct unique value in the `X-Mc-Correlation-ID`header, and try again. | | 400 | EMBOSSED_DATA_MISSING | Embossed data is missing for card contract. | Ensure that you pass embossed data either in a client or card contract creation request. It is mandatory to pass embossed data regardless of the type of card you want to issue. | | 400 | EVENT_CODE_NOT_SUPPORTED | Event code \ is not supported for contract with id \. | The provided `eventCode` is not configured in the CMS for you. Verify and correct the `eventCode` value in the request, and then try again. | | 404 | FEE_TYPE_DOES_NOT_EXIST | The given fee type identifier \ does not exists. | The provided `feeTypeId` is not configured in the CMS for you. Verify and correct the `feeTypeId` value in the request, and then try again. | | 409 | IDEMPOTENCY_KEY _ALREADY_IN_PROGRESS | The original request with the same Idempotency key is still being processed. | Ensure that the original request associated with the `Idempotency-Key` is fully processed before resending another request with the same key. | | 422 | IDEMPOTENCY_KEY_ALREADY _USED | Idempotency Key MUST not be reused across different payloads. | Make sure not to reuse the `Idempotency-Key` with other request body within 24 hours from the initial request. | | 400 | INSTITUTION_CONFIGURATION _NOT_FOUND_ERROR | User configuration was not found for id \. | Your API configuration appears to be incorrect. Verify that the `oauth_consumer_key` is correct. If the issue persists, contact your Mastercard Processing representative. | | 400 | INVALID_AUTHENTICATION_TYPE _CODE_FOR_PARAMETER_WITH _GIVEN_NAME | The authentication type code \ does not own a parameter with the name \. | The provided `authentication_parameter_name` to the specified `authentication_type_code` is not configured in the CMS for you. Verify and correct the value in the request, and then try again. | | 400 | INVALID_AUTHENTICATION _METHOD_FOR_GIVEN_TYPE | The given contract does not own a valid authentication method of the given type. | The provided `authentication_type_code` is not configured in the CMS for you. Verify and correct the value in the request, and then try again. | | 400 | INVALID_BIN_RANGE | Invalid card contract number BIN range. | Verify and correct the `cardContractNumber` value in the request, and then try again. | | 400 | INVALID_BRANCH_CODE | Invalid branch code. | The provided `branchCode` is not configured in the CMS for you. Verify and correct the `branchCode` value in the request, and then try again. | | 400 | INVALID_CLASSIFIER_CODE | Classifier with code \ not allowed for the contract with id \. | The provided `classifierCode` for the given card contract is not configured in the CMS for you. Verify and correct the `classifierCode` and `card_contract_id` values in the request, and then try again. | | 400 | INVALID_CLASSIFIER_VALUE | Invalid value \ for classifier with code \. | The provided classifier value for the given `classifier code` is not configured in the CMS for you. Verify and correct the `classifierValue` value in the request, and then try again. | | 400 | INVALID_DATE_FORMAT | Date has an invalid format. Correct format is `YYYY-MM-DD`. | Specify the correct date format in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | INVALID_DATE_FORMAT | Date time has an invalid format. Correct format is `YYYY-MM-DDThh:mm:ssZ`. | Specify the correct date format in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 412 | INVALID_ETAG | The `ETag` of resource does not match value in `If-Match` header. | Verify and correct the `If-Match` value in the request, and then try again. | | 404 | INVALID_EXPIRY_DATE | Expiry date \ does not match for the card contract with id \. | Verify and correct the `cardExpiryDate` value in the request, and then try again. | | 400 | INVALID_INSTITUTION _CONFIGURATION | Incorrect Officer ID in the API configuration. | Contact the Mastercard Processing representative to resolve an Officer ID mismatch between the API and the CMS. | | 400 | INVALID_PARAMETER_VALUE | The parameter code `MEMB_FEE_DELAY` does not own a parameter value 45. | Verify and correct the `parameter_code` and/or `parameterValue` in the request, and then try again. | | 400 | INVALID_PIN_BLOCK | Pin block is invalid. | Verify and correct the `newPinBlock` value in the request, and then try again. | | 400 | INVALID_PRODUCTION_CODE | Invalid production code. | The provided `productionCode` is not configured in the CMS for you. Verify and correct the `productionCode` value in the request, and then try again. | | 400 | INVALID_SEQUENCE_NUMBER | The card sequence number \ does not match the card contract with id \. | Verify and correct the `cardSequenceNumber` value in the request, and then try again. | | 400 | LUHN_CHECK_FAILED | Luhn check for card contract number failed. | Verify and correct the `cardContractNumber` value in the request, and then try again. | | 400 | MAX_NUMBER_OF_RECORDS _EXCEEDED | The response exceeded the recordset limit. | Narrow the query so the result set stays under the default limit of 1000 records. | | 400 | NO_PUBLIC_KEY_FINGERPRINT | Cannot find `publicKeyFingerprint` value inside JWE structure. | Ensure that the public key fingerprint value is correctly included in the JWE structure. Refer to the [documentation](https://developer.mastercard.com/platform/documentation/authentication/securing-sensitive-data-using-payload-encryption/#jwe-encryption) for detailed guidance on JSON Web Encryption used by Mastercard. | | 400 | NOT_ACCOUNT_CONTRACT | Contract with id \ is not an account. | Verify and correct the `contract_id` value in the request, and then try again. | | 400 | NOT_CARD_CONTRACT | Contract with id \ is not a card. | Verify and correct the `contract_id` value in the request, and then try again. | | 400 | NOT_SUFFICIENT_FUNDS | Not sufficient funds available for the contract with id \. | Verify the available balance on a given `contract_id`. | | 400 | NOT_UNIQUE_REFERENCE _NUMBER | UniqueReferenceNumber \ already exists. | Verify and correct the `uniqueReferenceNumber` value in the request, and then try again. | | 403 | OPERATION_DENIED | Operation \ is disabled in your API configuration. | Contact the Mastercard Processing representative if you want to use the operation. | | 403 | OPERATION_DENIED | Invalid or unsupported operation. Verify HTTP method, endpoint, and resource ID format. | Make sure you are calling the correct endpoint as defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | PIN_CHANGE_DISABLED | The card is currently being reissued, and the PIN change is temporarily disabled. | It is not allowed to change the PIN during the personalization process of the issued physical card. | | 400 | PIN_NOT_FOUND | Cannot find the PIN for the card contract with ID 10301. | The PIN has not been set yet for the specified card contract. | | 400 | PLASTIC_IS_MISSING | Plastic is missing for card contract with id \. | Ensure that you do not activate the card before personalization process is completed (card contract production status is `LOCKED`). | | 400 | PLASTIC_NOT_ACTIVE | Active plastic not found for the contract with id \. | Ensure that you do not post a transaction for a card contract that does not have the `Plastic` in active status. | | 400 | REISSUE TYPE_NOT _SUPPORTED | Reissue type \ is not supported for card contract with id \. | Verify and correct the `reissueType` value in the request, and then try again. You are allowed to use only the value set by Mastercard Processing. | | 400 | REQUEST_BODY_PROCESSING _ERROR | The given field \ has an invalid value. | Specify the correct field value defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_BODY_PROCESSING _ERROR | There is a problem with parsing the request body. | The three most common causes are: 1. Sending an unencrypted payload while the API expects a JWE payload (as specified [here](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#breaking-the-encrypted-payload-down)). 2. Sending a valid JWE payload, but the decrypted JSON does not match the API model defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md). 3. Sending an invalid JSON body. | | 400 | REQUEST_VALIDATION | Invalid field \ value in object \. Validation error: \. | Example of `Description`: "Invalid field `cardContractCustomData[0]( /documentation/api-reference/).tagValue` value in object `cardContractCreation`. Validation error: Field `tagValue` contains illegal characters." Specify the correct field value defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_VALIDATION | Invalid object \. Validation error: \. | Example of `Description`: "Invalid object `addressModification`. Validation error: One of fields: email, addressLine1, addressLine2, addressLine3, addressLine4 must be set." Specify the correct data in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_VALIDATION | Validation error: \. | Example of `Description`: "Validation error: The header `Customer-Public-Rsa-Key` is invalid." Specify the correct data in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_VALIDATION | Missing required HTTP header \
. | Specify the correct data in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_VALIDATION | Missing required request parameter \. | Specify the correct data in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | REVERSE_DOC_FLOW _INTERRUPT | `ServiceClass` is missing in the CMS for transaction with id \. | The provided `transaction_id` cannot be reversed. | | 400 | REVERSE_DOC_FLOW _INTERRUPT | `TransactionType` is missing in the CMS for the transaction with id \. | The provided `transaction_id` cannot be reversed. | | 400 | REVERSE_DOC_FLOW _INTERRUPT | `ServiceClassCode` for a transaction with id \ is not on the list of parameters permitted to reverse a transaction. | The provided `transaction_id` is not allowed to be reversed by the CMS. Contact the Mastercard Processing representative if you want to reverse this transaction. | | 400 | REVERSE_DOC_FLOW _INTERRUPT | `TransactionType` for a transaction with id \ is not on the list of parameters permitted to reverse the transaction. | Provided `transaction_id` is not allowed to be reversed by the CMS. Contact the Mastercard Processing representative if you want to reverse this transaction. | | 400 | SCALE_IS_NOT_SUPPORTED | Actual scale of precision: \ is not supported for \ field in the request body | Specify the correct data in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. | | 400 | STATUS_CODE_NOT _SUPPORTED | Status code \ is not supported for contract with id \. | Verify and correct the `statusCode` value in the request using only status code configured during the onboarding process, and then try again. | | 400 | STATUS_IS_WORSE | Status cannot be changed. Present status is worse. | Card statuses belong to one of three levels: Level 1: 00, 05, 59 Level 2: 04, 41, 47 Level 3: 57 Within one level, the status can be changed freely, and it can be changed to one at a higher level but never to one at a lower level. | | 400 | TARIFF_CODE_DOES_NOT _EXIST | The given tariff code \ does not exist. | Verify and correct the `tariffCode` value in the request, and then try again. | | 400 | TOO_MANY_CLIENTS _FOUND | There is more than one `clientId` with the same identification number. | Ensure that each client has a unique identification number. If duplicates exist, send the `updateClient` request to make the identification number unique across all clients stored in the CMS, and then try again. | | 400 | TOO_MANY_CONTRACTS _FOUND | There is more than one contract with the same cbs number. | Ensure that each card contract has a unique CBS number. If duplicates exist, send the `updateCardContract` request to make the CBS number unique across all card contracts stored in the CMS, and then try again. | | 404 | TRANSACTION_DOES _NOT_EXIST | Transaction with id \ not found. | Verify and correct the `transaction_id` value in the request, and then try again. | | 400 | TRANSACTION_NOT_ALLOWED | Transaction not allowed for the contract with id \. | Ensure that you do not post transaction with a transaction type that is not allowed for the contract in a specific state. For example, an account contract with an active charge-off or in a delinquency level 3 or greater. | | 400 | UNEXPECTED_DOCUMENT _STATUS | Transaction with id \ not in the postingStatus permitted to be reversed. | The provided `transaction_id` cannot be reversed. | | 400 | UNSUPPORTED_AUTHENTICATION _PARAMETER_NAME | The given authentication parameter name \ is not supported. | The provided authentication parameter name is not configured in the CMS for you. Verify and correct the `AuthenticationParameter.name` value in the request, and then try again. | | 400 | UNSUPPORTED_AUTHENTICATION _TYPE_CODE | The authentication type code \ does not exist. | The provided `authenticationTypeCode` is not configured in the CMS for you. Verify and correct the `authenticationTypeCode` value in the request, and then try again. | | 415 | UNSUPPORTED_CHARSET_ERROR | Charset \ is not supported. Only UTF-8 charset is supported. | Specify the correct data in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-core/documentation/api-reference/index.md), and try again. For the Mastercard Processing API, the `Content-Type` header must be: • `application/merge-patch+json;charset=utf-8` for `PATCH` requests • `application/json;charset=utf-8` for all other HTTP methods | | 404 | USAGE_LIMIT_CODE_DOES_NOT _EXIST | Usage limit code \ does not exist for contract with id \. | The provided `usage_limit_code` is not configured in the CMS for you. Verify and correct the `usage_limit_code` value in the request, and then try again. | | 400 | USAGE_LIMIT_EXCEEDED | The transaction amount exceeds the maximum value permitted by the Usage Limit \. | Adjust the given `usageLimitCode` properties (by sending a `PUT` request to the `/contracts/{contract_id}/usage-limits/{usage_limit_code}` endpoint), and try again. | ### Sample Errors {#sample-errors} The following is a sample of the error response when you send a `GET` request to the `/cards/{card_contract_id}/plastics` endpoint for a non-existent card contract. ```json { "Errors": { "Error": [ { "Source": "MASTERCARD PROCESSING", "ReasonCode": "CARD_CONTRACT_DOES_NOT_EXIST", "Description": "Card contract with id 10001 not found.", "Recoverable": false } ] } } ``` The following is a sample of the error response when you activate a card contract by sending a `PUT` request to the `/cards/{card_contract_id}/active` endpoint before the card production. ```json { "Errors": { "Error": [ { "Source": "MASTERCARD PROCESSING", "ReasonCode": "PLASTIC_IS_MISSING", "Description": "Plastic is missing for card contract with id 10102.", "Recoverable": false } ] } } ```