# Code and Formats source: https://developer.mastercard.com/mdes-digital-enablement/documentation/code-and-formats/index.md ## Error Codes {#error-codes} The error message returned will depend on which API generated the error and at what point the request failed. Error messages will be in one of two formats: * [Gateway Error Messages](https://developer.mastercard.com/mdes-digital-enablement/documentation/code-and-formats/index.md#gateway-error-messages) - returned from the gateway and typically occur when OAUTH authentication fails * [API Error Messages](https://developer.mastercard.com/mdes-digital-enablement/documentation/code-and-formats/index.md#api-error-messages) - returned from the MDES application and typically occur for incorrect input or cryptography errors. Alert: To ensure forward-compatibility, client implementations must be resilient to new elements being added 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: ```json { "Errors": { "Error": [ { "Source": "Gateway", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": null } ] } } ``` Field explanations: * **source** - the application that generated this error. Every error message that is generated and returned by the application will have this field equal to `INPUT`. When the value of the source field is something else, it means the error was generated elsewhere. * **reasonCode** - a unique constant identifying the error case encountered during transaction processing. * **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 a success. However, if the error is related to some unexpected timeout with the service, retrying the call could result in a successful response. Note: For more information gateway error messages including the error codes, please refer to [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/) | Reason Code | Detail | |--------------------------------|----------------------------------------------------------------------------------------------------| | UNSUPPORTED_CONTENT_TYPE | The request Content-Type is not supported for this service. | | INVALID_OAUTH_SBS | Problem with signature base string | | INVALID_OUTH_CONSUMER_KEY | Consumer key parameter must be 97 characters long, split by an exclamation mark symbol. | | INVALID_OAUTH_SIGNATURE_METHOD | Invalid oauth_signature_method. Supported: RSA-SHA1, RSA-SHA256, RSA-SHA512. | | INVALID_OAUTH_TIMESTAMP | Invalid Timestamp | | OAUTH_NONCE_USED | Nonce was already used within the current time window. | | INVALID_BODY_HASH | The provided oauth_body_hash does not match the signature method hash of the request payload | | INVALID_CLIENT_ID | The provided clientId was not found. | | INVALID_KEY_ID | Project does not contain key The provided key was not found. The signing certificate is not valid. | | AUTHENTICATION_FAILED | OAuth signatures did not match. | | TRANSFORM_ERROR | Transformation of request body failed. Transformation of response body failed | | SERVER_ERROR_100 | Internal server error. | | SERVER_ERROR_101 | Internal server error. | | SERVER_ERROR_102 | Internal server error. | | SYSTEM_ERROR | An unexpected error has occurred with the service you have requested. | ### API Error Messages {#api-error-messages} #### General Error Response {#general-error-response} A HTTP response code of 200 will be returned if the call was successfully received and accepted for processing. Any errors that subsequently occur during processing are returned in the response payload as below: #### Invalid Field Value {#invalid-field-value} The value is not allowed for the field. #### HTTP status code {#http-status-code} `200` ```json { "errorCode": "string", "errorDescription": "string", "responseHost": "site2.payment-app-provider.com", "responseId": 123456, "errors": [ { "source": "MDES", "reasonCode": "INVALID_FIELD_VALUE", "description": "string", } ] } ``` **Resolution** The description will contain details of the field that contains the incorrect value. Correct the data in the field in accordance with the [API Reference](https://developer.mastercard.com/mdes-digital-enablement/documentation/api-reference/index.md) #### Authorization Failed {#authorization-failed} Returned if the Client ID has not been enabled for the Digital Enablement API. **HTTP status code** `200` ```json { "errorCode": "AUTHORIZATION_FAILED", "errorDescription": "Authorization Failed", "responseId": "111111", "responseHost": "site2.payment-app-provider.com", "errors": [ { "source": "INPUT", "description": "Authorization Failed", "reasonCode": "AUTHORIZATION_FAILED", } ] } ``` **Resolution** Contact your Mastercard CIS implementation manager to ensure all the necessary on-boarding steps have been completed. #### Cryptography Error {#cryptography-error} A cryptography error will occur when the payload has not been encrypted correctly. **HTTP status code** `200` ```json { "errorCode": "CRYPTOGRAPHY_ERROR", "errorDescription": "Cryptography Error", "responseId": "111111", "responseHost": "site2.payment-app-provider.com", "errors": [ { "source": "INPUT", "description": "Cryptography Error", "reasonCode": "CRYPTOGRAPHY_ERROR", } ] } ``` **Resolution** A cryptography error could be generated for a number of reasons. Typically this error occurs when the service has been unable to decrypt the payload supplied in the API request. Check the correct keys are being used as separate encryption keys are required for MTF and Production. Please also refer to the API reference for [guidance on encryption](https://developer.mastercard.com/mdes-digital-enablement/documentation/api-reference/index.md#encrypt-decrypt-configuration) #### Invalid Field Length {#invalid-field-length} The API request contains data in a field which exceeds the maximum length permitted. **HTTP status code** `200` ```json { "errorCode": "INVALID_FIELD_LENGTH", "errorDescription": "Invalid Field Length - requestId", "responseId": "111111", "responseHost": "site2.payment-app-provider.com", "errors": [ { "source": "INPUT", "description": "Invalid Field Length - requestId", "reasonCode": "INVALID_FIELD_LENGTH", } ] } ``` **Resolution** The description will contain details of which field has exceeded its maximum length. Correct the data in the field in accordance with the [API Reference](https://developer.mastercard.com/mdes-digital-enablement/documentation/api-reference/index.md) #### Invalid Field Format {#invalid-field-format} The API request contains data in a field which is incorrectly formatted. **HTTP status code** `200` ```json { "errorCode": "INVALID_FIELD_FORMAT", "errorDescription": "Invalid Field Format - requestId", "responseId": "111111", "responseHost": "site2.payment-app-provider.com", "errors": [ { "source": "INPUT", "description": "Invalid Field Format - requestId", "reasonCode": "INVALID_FIELD_FORMAT", } ] } ``` #### Missing Required Field {#missing-required-field} The API request is missing a required mandatory field. **HTTP status code** `200` ```json { "errorCode": "MISSING_REQUIRED_FIELD", "errorDescription": "Missing Required Field - requestId", "responseId": "111111", "responseHost": "site2.payment-app-provider.com", "errors": [ { "source": "INPUT", "description": "Missing Required Field - requestId", "reasonCode": "MISSING_REQUIRED_FIELD", } ] } ``` **Resolution** Correct the request to contain all mandatory field as described in the [API Reference](https://developer.mastercard.com/mdes-digital-enablement/documentation/api-reference/index.md) #### Transact Error Response {#transact-error-response} #### HTTP status code {#http-status-code-1} `200` ```json { "source": "string", "errorCode": "string", "description": "string", "reasonCode": "string", "errorDescription": "string" } ``` ## Reason Codes {#reason-codes} | Reason Code | Detail | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_JSON | The JSON could not be parsed | | UNRECOGNISED_FIELD | The field name is not valid for the object | | AUTHORIZATION_FAILED | The request failed to present a valid cert to access the API. | | INVALID_FIELD_FORMAT | The field is not in the correct format. For instance, it should be a number but is a string. | | INVALID_FIELD_LENGTH | The value does not fall between the minimum and maximum length for the field. | | INVALID_FIELD_VALUE | The value is not allowed for the field. | | INVALID_RESPONSE_HOST | The requested response host is invalid. | | NO_RESPONSE_FROM_ISSUER | The issuer did not respond to the network message in the allotted time. An asynchronous message will be sent. The Token Requestor should retry after the time specified in the retry-after header. | | MISSING_REQUIRED_FIELD | A required field is missing. | | CRYPTOGRAPHY_ERROR | There was an error decrypting the encrypted payload. | | INTERNAL_SERVICE_FAILURE | MDES had an internal exception. | | INVALID_PAN | The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly. The request may be retried if the data is re-entered correctly. | | MISSING_EXPIRY_DATE | The expiry date is required for this product but was missing. Retry the request supplying the expiry date for this card. | | DUPLICATE_REQUEST | The PAN has already been provisioned to the device or the same request is currently being processed. | | PAN_INELIGIBLE | The PAN is not in an approved account range for MDES. | | INVALID_TASK_ID | The taskId could not be found or, for inbound calls, the taskId was not unique. | | INVALID_TOKEN_STATUS | The token is in an invalid status for the requested operation. For instance, trying to unsuspend a deleted token. | | MAX_ATC_LIMIT_REACHED | Maximum number of Application Transaction Counter limit reached. | | NO_ACTIVE_TOKENS | There are no active (not suspended) Tokens for the given Account PAN and consumer account. | | TOKEN_PAN_NOT_FOUND | The token pan that was supplied in the request could not be found. This could be an invalid token or a token number, token expiration mismatch, or the token is expired. | | INVALID_TOKEN_UNIQUE_REFERENCE | The token unique reference (TUR) could not be found. | | INVALID_PAN_UNIQUE_REFERENCE | The PAN unique reference (PUR) could not be found. | | MISSING_CONSENT_OR_AUTH_FLAG | Validation failed due to missing consent or authentication data when either cardHolderConsentCapturedFlag or authenticationPerformedFlag is set to FALSE. | ## HTTP Response Codes {#http-response-codes} | HTTP Status | Detail | |---------------------------|-----------------------------------------------------------------------------------------------------------------------------| | 200 OK | Request succeeded and processed ok | | 401 Unauthorized | Authentication is required and has failed or has not yet been provided | | 403 Forbidden | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | | 404 Not Found | The requested resource could not be found | | 500 Internal Server Error | An unexpected condition has occurred on the Mastercard server | | 503 Service Unavailable | The Server is currently unavailable | ## Authentication Method Codes {#authentication-method-codes} Specifies the authentication method type being utilized. | Value | Meaning | Value Required | |-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|----------------| | TEXT_TO_CARDHOLDER_NUMBER | Text message to Cardholder's mobile phone number. Value will be the Cardholder's masked mobile phone number. | Yes | | EMAIL_TO_CARDHOLDER_ADDRESS | Email to Cardholder's email address. Value will be the Cardholder's masked email address. | Yes | | CARDHOLDER_TO_CALL_AUTOMATED_NUMBER | Cardholder-initiated call to automated call center phone number. Value will be the phone number for the Cardholder to call. | Yes | | CARDHOLDER_TO_CALL_MANNED_NUMBER | Cardholder-initiated call to manned call center phone number. Value will be the phone number for the Cardholder to call. | Yes | | CARDHOLDER_TO_VISIT_WEBSITE | Cardholder to visit a website. Value will be the website URL. | Yes | | CARDHOLDER_TO_USE_ISSUER_MOBILE_APP | Cardholder to use a specific mobile for authentication. Value will be an IssuerMobileApp object with the applicable activation app method for the device. | Yes | | ISSUER_TO_CALL_CARDHOLDER_NUMBER | Issuer-initiated voice call to Cardholder's phone. Value will be the Cardholder's masked voice call phone number. | Yes | ## Recommendation Reason Codes {#recommendation-reason-codes} Code indicating the reasons the Token Requestor is suggesting the digitization decision. Recommendation reasons for an 'APPROVED' recommendation must be one or more of the following: | Value | Meaning | |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | LONG_ACCOUNT_TENURE | Account has existed for an extended period of not less than one year. A Token Requestor may determine a longer account tenure to qualify for this reason. | | GOOD_ACTIVITY_HISTORY | There has been financial activity linked to the account for at least and within a period of not less than six months; no suspicious activity is linked to the account within a period of at least one year. | | ADDITIONAL_DEVICE | The digitization is for an additional device for the same Account PAN and consumer account. There must be a currently active (not suspended) Token that was previously digitized and activated on an existing device for the same Account PAN and consumer account. | | SOFTWARE_UPDATE | The digitization has been requested due to an authenticated operating system or other software update being installed on the device, causing mobile payment data to be wiped and unable to be restored. This digitization must be for the same paymentAppInstanceId to which a Token was previously digitized and activated for the same Account PAN and consumer account. | Recommendation reasons for a 'REQUIRE_ADDITIONAL_AUTHENTICATION' or 'DECLINED' recommendation must be one or more of: | Value | Meaning | |--------------------------------|----------------------------------------------------------------------| | ACCOUNT_TOO_NEW_SINCE_LAUNCH | Account is considered new relative to Token Requestor service launch | | ACCOUNT_TOO_NEW | Account is considered new relative to provisioning request | | ACCOUNT_CARD_TOO_NEW | Account/card is considered new relative to provisioning request | | ACCOUNT_RECENTLY_CHANGED | Changes have recently been made to account data | | SUSPICIOUS_ACTIVITY | Suspicious activity has been linked to this account | | INACTIVE_ACCOUNT | Inactive account | | HAS_SUSPENDED_TOKENS | Device contains suspended tokens | | DEVICE_RECENTLY_LOST | Device has recently been reported lost | | TOO_MANY_RECENT_ATTEMPTS | Excessive recent tokenization attempts to this device | | TOO_MANY_RECENT_TOKENS | Excessive recent tokenizations to this device | | TOO_MANY_DIFFERENT_CARDHOLDERS | Excessive non-matching cardholder names within the device | | LOW_DEVICE_SCORE | Low device score | | LOW_ACCOUNT_SCORE | Low account score | | OUTSIDE_HOME_TERRITORY | Non-domestic tokenization attempt | | UNABLE_TO_ASSESS | Unable to provide recommendation due to system issues. | | HIGH_RISK | High fraud risk identified. Enhanced authentication recommended. |