# Code and Formats source: https://developer.mastercard.com/mastercard-processing-mastercard/documentation/code-and-formats/index.md ## HTTP Response Codes {#http-response-codes} | HTTP Response Code | Response Description | Resolution Tips | |------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 (OK) | The request was completed successfully. | No action needed - request processed successfully. | | 400 (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) | Missing or invalid authentication token. | Verify authentication credentials, refresh tokens if expired, and ensure that proper authorization headers are included. | | 403 (FORBIDDEN) | 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) | The requested resource was not found. | Verify the resource URL/ID is correct and the resource exists. Check for typos in the endpoint path. | | 405 (METHOD NOT ALLOWED) | The HTTP method used is not allowed for the requested resource. | Ensure you are using the correct HTTP method for this endpoint, based on the API specification. | | 409 (CONFLICT) | A conflict occurred due to a resource state that prevents processing the request (for example, conflicting updates or existing resource state). | Wait until the original request associated with the `Idempotency-Key` is completed before attempting a retry. Do **not** resend the request while it is still being processed, as the system will return the same conflict response. | | 415 (UNSUPPORTED MEDIA TYPE) | The server does not support the request payload's media type. | For Mastercard Processing API, the `Content-Type` header must be `application/json;charset=utf-8`. | | 422 (UNPROCESSABLE ENTITY) | Resource already exists/resource has been modified. | Generate a new, unique `Idempotency-Key` for every request that contains different payload data. Reusing an `Idempotency-Key` within the 24-hour retention window will always result in this error. | | 429 (TOO MANY REQUESTS) | The client has sent more requests than allowed by the configured throttling limits. | Delay requests and retry after a short interval. | ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by the Mastercard Processing - Mastercard Services API, error codes can be returned by the Mastercard gateway, which verifies your request's signature and routes to the correct location. For further information about the 4xx response codes returned by the gateway and their possible resolutions, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/). ## Error Structure {#error-structure} To provide a consistent experience across all Mastercard APIs, the Mastercard Processing - Mastercard Services API follows the standard structure for each scenario that can occur. **Single error:** ```json { "Errors": { "Error": [ { "source": "", "reasonCode": "", "description": "", "recoverable": "", "details": "
" } ] } } ``` **Multiple errors:** ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": "", "Details": "" },{ "Source": "", "ReasonCode": "", "Description": "", "Recoverable": "", "Details": "" } ] } } ``` | Field | Description | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Source** | The application that generated this error. Every error message that is generated and returned by the gateway will have this field set to `Gateway`. If the field value is `MASTERCARD PROCESSING`, then the error is generated by the Mastercard Processing - Mastercard Services application. | | **ReasonCode** | A unique constant identifies the error case encountered when any Mastercard Processing - Mastercard Services API is called. For example, `NOT_FOUND` is used when the requested resource does not exist. | | **Description** | Description of the `ReasonCode` field provided with additional details. | | **Recoverable** | It 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 request parameter, 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** | Provide detailed error information wherever appropriate to help in resolving errors. | ## 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 | 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 | 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` header, and try again. | | 409 | IDEMPOTENCY_KEY_ALREADY_IN_PROGRESS | The 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. | | 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 Card Management System (CMS). | | 400 | NO_PUBLIC_KEY_FINGERPRINT | Cannot find publicKeyFingerprint value inside the 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. | | 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-mastercard/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-mastercard/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-mastercard/documentation/api-reference/index.md), and try again. | | 400 | REQUEST_VALIDATION | Invalid object \. Validation error: \. | Specify the correct data in the request defined in the [OpenAPI Specification](https://developer.mastercard.com/mastercard-processing-mastercard/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-mastercard/documentation/api-reference/index.md), and 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-mastercard/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} * Sample `404` error response from the `POST /cards/searches` when the request contains card identifier that does not exist in the Mastercard Processing CMS system: ```json { "Errors": { "Error": [ { "Source": "MASTERCARD PROCESSING", "ReasonCode": "CARD_CONTRACT_DOES_NOT_EXIST", "Description": "Card contract with id 10001 not found.", "Recoverable": false } ] } } ``` * Sample `403` error response from the `POST /cards/searches` when CIS project has not been completed and the endpoint is not enabled yet in the Mastercard Processing system: ```json { "Errors": { "Error": [ { "Source": "MASTERCARD PROCESSING", "ReasonCode": "OPERATION_DENIED", "Description": "Operation getMastercardEncryptedRequest is disabled in your API configuration.", "Recoverable": false } ] } } ```