# Code and Formats source: https://developer.mastercard.com/mastercard-processing-digital/documentation/code-and-formats/index.md ## HTTP Response Codes {#http-response-codes} | **Status Code** | **Response** | **Description** | |-----------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 | OK | Everything worked as expected. | | 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`). | | 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/json;charset=utf-8`. | | 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 | CLIENT_DOES_NOT_EXIST | Client with id `client_id` not found. | Verify and correct the `client_id` value in the request, and then try again. | | 404 | CARD_CONTRACT_DOES _NOT_EXIST | Card contract with id `card_contract_id` not found. | Verify and correct the `card_contract_id` value in the request, and then try again. | | 400 | CARD_CONTRACT_NAME _IS_MISSING | Card Contract Name is missing for the card contract with id `card_contract_id`. | Verify if one of the following values have been provided: `clientPersonalData.firstName` and `clientPersonalData.lastName` or `clientPersonalData.shortName` during the client creation or `cardContractName` during the card contract creation using the [Mastercard Processing Core API](https://developer.mastercard.com/mastercard-processing-core/documentation/). If not, you must update client or card contract data in the CMS using the [Mastercard Processing Core API](https://developer.mastercard.com/mastercard-processing-core/documentation/) or provide `cardContractName` in the Digital API request. | | 400 | CARD_CONTRACT_PLASTIC _STATUS_IS_WRONG | Card contract plastic for card contract `card_contract_id` is not found or is not active. | Verify and correct the `card_contract_id` value in the request, and then try again. You can enroll only an active card to Click to Pay. | | 400 | CARD_CONTRACT_STATUS _IS_WRONG | Card having card contract id `card_contract_id` is not active. | Verify and correct the `card_contract_id` value in the request, and then try again. You can enroll only active card to Click to Pay. | | 400 | CARD_CONTRACT_STATUS _IS_WRONG | Card contract with id `card_contract_id` in wrong status to relink tokens. | Verify and correct the `card_contract_id` or/and `newCardContractId` value in the request, and then try again. You can relink tokens only to an active card contract. | | 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. | | 400 | DUPLICATED_X_MC _CORRELATION_ID | The given `X-Mc-Correlation_Id` header was used in previous request. | Specify the correct unique value in the `X-Mc-Correlation-Id` or `Correlation-Id` header, and try again. | | 409 | IDEMPOTENCY_KEY_ALREADY _IN_PROGRESS | Original request with the same Idempotency Key is still being processed. | Ensure 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 | INVALID_DATA_PROVIDED | Invalid data in one or more fields: `nonce`, `nonceSignature`, or `walletCertificate` to generate IIDD. | Verify and correct the data provided in the request, and then try again. | | 500 | 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_TOKEN | Token not found or is deactivated in the CMS. | Verify and correct the `tokenNumber` value in the request, and then try again. Ensure the provided `tokenNumber` exists and is not deactivated. Additionally, for the `relinkTokensToAnotherCard`, make sure both cards belong to the same `productCode`. | | 400 | INVALID_EXPIRY_DATE | Expiry date `cardExpiryDate` does not match for the card contract with id `card_contract_id`. | Verify and correct the `cardExpiryDate` value in the request, and then try again. | | 400 | NO_PUBLIC_KEY _FINGERPRINT | Cannot find `publicKeyFingerprint` value inside JWE structure. | Ensure 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_CARD_CONTRACT | Contract with id `card_contract_id` is not a card. | Verify and correct the `card_contract_id` 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-digital/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_BODY_PROCESSING _ERROR | The given field \ has invalid value. | Specify the correct field value defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-digital/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_BODY_PROCESSING _ERROR | There is a problem with parsing 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-digital/documentation/api-reference/index.md). 3. Sending an invalid JSON body. | | 400 | REQUEST_VALIDATION | Invalid field \ value in object \. Validation error: \. | Specify the correct field value defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-digital/documentation/api-reference/index.md), and try again. | | 404 | TOKEN_DOES_NOT_EXIST | Token with number `token_number` not found. | Verify and correct the `token_number` 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-digital/documentation/api-reference/index.md), and try again. For the Mastercard Processing API, the `Content-Type` header must be `application/json;charset=utf-8`. | ### Sample Errors {#sample-errors} The following is a sample error response when updating STIP balance for an account contract by sending a `PUT` request to the `/accounts/{account_contract_id}/stip-balance` endpoint: ```JSON { "Errors": { "Error": [ { "Source": "MASTERCARD PROCESSING", "ReasonCode": "CARD_CONTRACT_DOES_NOT_EXIST", "Description": "Card contract with id 10001 not found.", "Recoverable": false } ] } } ```