# Code and Formats source: https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md Alert: **Please note that the encryption functionality for the Search API is currently not available in the Sandbox environment. We recommend that customers perform their encryption testing in the MTF environment. This will help in identifying any potential issues and ensure that the encryption works as expected before deploying in Production environment.** This section describes errors that may be returned either from the gateway or the MDES Customer Service API. The error message format 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 depending on the type of error. 1. [Application Error Messages](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#reason-codes) - returned from the service application and typically occur for incorrect input, missing/invalid conditional fields or unsupported actions. 2. [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/) - returned from the gateway and typically occur when OAUTH authentication fails. Alert: To ensure forward-compatibility, client implementations must be resilient to new elements being added to the API responses in the future. ## Error Structure {#error-structure} ### JSON Error Format {#json-error-format} ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "EMPTY_RESULT", "ErrorCode": [], "Description": "Empty result for the given request.", "Recoverable": [] } ] } } ``` ### Field explanations: {#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. * **description** - Description of the Reason Code field with additional details * **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. This is boolean type parameter returning either true or false. ## Reason Codes {#reason-codes} | ReasonCode | Description | http code | Resolution Tips | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [NOT_SUPPORTED](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#not-supported) | Displayed when the API, or particular usage of the API, is not supported. | 400 | Either the token type or status do not support the operation. Valid API operations performed are described in the [Requests by Token State](https://developer.mastercard.com/mdes-customer-service/documentation/api-basics/index.md#requests-by-token-state) table. | | [EMPTY_RESULT](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#empty-result) | Displayed when the API did not process successfully because the input parameter used could not be found in the system. Applies to 'action-like' API requests | 400 | Provide valid TokenUniqueReference and account information and check all MDES on-boarding steps have been completed | | [INVALID_TOKEN_STATUS](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-token-status) | Displayed when an action is requested that would change the token status, but that request is invalid given the current token status. | 400 | The current token status does not support the operation. Valid API operations performed are described in the [Requests by Token State](https://developer.mastercard.com/mdes-customer-service/documentation/api-basics/index.md#requests-by-token-state) table. | | [INVALID_WORKFLOW](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-workflow) | Displayed when an action is requested that would not change the token status, but that request is invalid given the current token status. | 400 | Request valid API operations based on token type and state as described in the [Requests by Token State](https://developer.mastercard.com/mdes-customer-service/documentation/api-basics/index.md#requests-by-token-state) table. | | [INVALID_CONDITIONAL_FIELD](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-conditional-field) | Displayed when multiple conditional fields are present. | 400 | Provide the correct combination of conditional fields in the request. | | [INVALID_FIELD_FORMAT](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-field-format) | Displayed when invalid characters are included in a particular field | 400 | Provide a valid field format in the request. | | [INVALID_FIELD_LENGTH](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-field-length) | Displayed when the number of characters provided in a specific field in the request is either too few or too many | 400 | Provide the correct number of characters required in a field. | | [INVALID_FIELD_VALUE](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-field-value) | Displayed when the value provided in a specific field in the request contains an unexpected or unsupported value. | 400 | Provide a valid value in the request. | | [INVALID_REQUEST](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-request) | Displayed for an invalid request. | 400 | Provide a valid API request. | | [MISSING_CONDITIONAL_FIELD](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#missing-required-field) | Displayed when the request is missing a field that was expected given a choice of fields to use, given system state, or other system constraints. | 400 | Provide the missing field in the request. | | [MISSING_REQUIRED_FIELD](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#missing-required-field) | Displayed when the request is missing a mandatory field. | 400 | Provide the mandatory fields in the request. | | [CRYPTOGRAPHY_ERROR](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#cryptography-error) | Displayed when the request receives error while performing crypto operation. | 400 | Provide a valid value in the request. | | [PAGE_NOT_FOUND](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#page-not-found) | Displayed when the offset value passed in the request is greater than total token count. | 400 | Provide a valid offset value in the request. | | [INVALID_AUTH_REQ_CORR_ID](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#invalid-authorization-required-correlation-id) | The auth request correlation ID provided was invalid. | 400 | Provide a valid value in the request. | | [DUPLICATE_REQUEST](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#duplicate-request) | The same request is currently being processed. | 400 | Wait for the request to be processed before trying again. | ### Not Supported {#not-supported} The API, or particular usage of the API, is not supported. For example, Token Activate is not supported for CoF tokens. APIs affected by this error include Token Activate, Token Update, Transactions, Token Activation Methods, Token Resend Activation Code, Token Reset Mobile PIN, Update Token Assurance, or Notify Authentication Decision. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "SYSTEM", "ReasonCode": "NOT_SUPPORTED", "ErrorCode": "E0010002", "Description": "Not Supported" } ] } } ``` **Resolution** The API, or particular usage of the API, is not supported. Valid API operations will depend on token type and state. Refer to [Requests by Token State](https://developer.mastercard.com/mdes-customer-service/documentation/api-basics/index.md#requests-by-token-state) for more information. ### Empty Result {#empty-result} The API did not process successfully because the input parameter used could not be found in the system or the client may not have completed the necessary MDES on-boarding steps. Applies to 'action-like' API requests, including Token Suspend, Token Activate, Token Update, Token Suspend, Token Unsuspend, Token Delete, Token Status History, Token Comments, Transactions, Token Activation Methods, Token Resend Activation Code, Token Reset Mobile PIN, Update Token Assurance, or Notify Authentication Decision. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "EMPTY_RESULT", "ErrorCode": "E0020001", "Description": "Empty result for the given request." } ] } } ``` **Resoultion** First check the TokenUniqueReference or account information is valid. Secondly check with your Mastercard representative that all MDES on-boarding steps have been completed. This error may also occur when using Token Update to update an FPAN, PSN and/or an expiry date and one of the tokens associated to this FPAN is in 'deleted' or 'unmapped' status. ### Invalid Token Status {#invalid-token-status} Returned when an action is requested that would change the token status, but that request is invalid given the current token status. For example this error would be returned if token status is Active or Suspended, and an Activate request is received or When token status is Deleted and a Suspend request is received. Token Activate, Token Suspend, or Token Unsuspend may receive this error. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "INVALID_TOKEN_STATUS", "ErrorCode": "E0010033", "Description": "Invalid Token Status." } ] } } ``` **Resolution** The API, or particular usage of the API, is invalid. Valid API operations will depend on token type and state. Refer to [Requests by Token State](https://developer.mastercard.com/mdes-customer-service/documentation/api-basics/index.md#requests-by-token-state) for more information. ### Invalid Workflow {#invalid-workflow} Returned when an action is requested that would not change the token status, but that request is invalid given the current token status. * When token status is IN PROGRESS, and an Update or Reset Mobile PIN request is received. * When token status is ACTIVE or SUSPENDED, and an Activation Methods request is received. * When token status is Deleted, and an Activation Methods, Update or Reset Mobile PIN request is received. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "SYSTEM", "ReasonCode": "INVALID_WORKFLOW", "ErrorCode": "E0010034", "Description": "Invalid Workflow." } ] } } ``` **Resoultion** The API, or particular usage of the API, is invalid. Valid API operations will depend on token type and state. Refer to [Requests by Token State](https://developer.mastercard.com/mdes-customer-service/documentation/api-basics/index.md#requests-by-token-state) for more information. ### Invalid Conditional Field {#invalid-conditional-field} Returned when an action is requested that would not change the token status, but the request is invalid given the current token status. This may occur when multiple conditional fields are present such as TokenUniqueReference and Account PAN. Apples to Token Activate, Token Update, or Search API. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "INVALID_CONDITIONAL_FIELD", "ErrorCode": "E0010001", "Description": "Invalid Conditional Field - Multiple conditional fields present." } ] } } ``` **Resolution** Could occur if more than one conditional parameter is present in a search request (TokenUniqueReference, Account PAN, PaymentAppInstanceId, Token, Comment Id, or AlternateAccountId) Also occurs when the token update API is called with incorrect conditional field combinations such as IssuerProductConfigurationId and either NewAccountPan, AccountPanSeqNum or ExpirationDate or TokenUniqueReference with CurrentAccountPan. ### Missing Conditional Field {#missing-conditional-field} Returned when the request is missing a field that was expected given a choice of fields to use, given system state, or other system constraints. As example when a Token Activate request contains either Account PAN or Payment App Instance ID, but not both.- When any of the parameters (TokenUniqueReference, Account PAN, PaymentAppInstanceId, Token, Comment Id, or AlternateAccountId) are not available for a search request. Applies to Token Activate, Token Update, or Search **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "MISSING_CONDITIONAL_FIELD", "ErrorCode": "E0010038", "Description": "Missing Conditional Field - (NewAccountPan/ExpirationDate/AccountPanSequenceNumber)" } ] } } ``` **Resolution** Supply the missing conditional fields as indicated in the Description ### Invalid Field Format {#invalid-field-format} Returned when invalid characters are included in a particular field, such as alphabetic characters when the field can only contain numeric characters. For example, Account PAN not numeric or ExpirationDate does not match valid MMYY format. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "INVALID_FIELD_FORMAT", "ErrorCode": "E0010010", "Description": "Invalid Field Format - AccountPan" } ] } } ``` **Resolution** Correct incorrectly formatted field(s) indicated in the Description ### Invalid Field Length {#invalid-field-length} Returned when maximum or minimum field lengths are not met. This applies to Token Activate, Token Update, Token Suspend, Token Unsuspend, Token Delete, Token Status History , Token Comments Transactions, Token Activation Methods, Token Resend Activation Code, Token Reset Mobile PIN, Update Token Assurance or Search, Notify Authentication Decision. As example, this may occur when the length of the Account PAN is not between 9-19 digits in a Search request. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "INVALID_FIELD_LENGTH", "ErrorCode": "E0010023", "Description": "Invalid Field Length - AuditInfo.Phone" } ] } } ``` **Resolution** Reduce the length of the data in the field indicated in the Reason Code and Description ### Invalid Field Value {#invalid-field-value} Returned when the value provided in a specific field in the request contains an unexpected or unsupported value. As example, a token suspend request when the device for the token is lost or stolen or the token for the device was involved in fraudulent transaction. This error applies to Token Activate, Token Update, Token Suspend, Token Unsuspend, Token Delete, Token Resend Activation Code, Token Reset Mobile PIN, or Notify Authentication Decision. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "INVALID_FIELD_VALUE", "ErrorCode": "E0010031", "Description": "Invalid Field Value - ReasonCode" } ] } } ``` **Resolution** Check and amend the values supplied in the field indicated in the 'Description' ## Missing Required Field {#missing-required-field} Returned when the request is missing a mandatory field. As example when the Token Unique Reference is missing from a Token Suspend request.Applies to Search, Token Activate, Token Update, Token Suspend, Token Unsuspend, Token Delete, Token Status History, Token Comments, Transactions, Token Activation Methods, Token Resend Activation Code, Token Reset Mobile PIN, Update Token Assurance, or Notify Authentication Decision **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "MISSING_REQUIRED_FIELD", "ErrorCode": "E0010045", "Description": "Missing Required Field - TokenUniqueReference" } ] } } ``` **Resolution** Supply the missing field indicated in the 'Description' ## Invalid Request {#invalid-request} Returned when a given request is invalid. Used when the provided Token or Account PAN does not belong to the requestor or whenever the client does not have access to the given account ranges. Applies to Search, Token Activate, Token Update, Token Suspend, Token Unsuspend, Token Delete, Token Status History, Token Comments, Transactions, Token Activation Methods, Token Resend Activation Code, Token Reset Mobile PIN, Update Token Assurance, or Notify Authentication Decision. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "SYSTEM", "ReasonCode": "INVALID_REQUEST", "ErrorCode": "E0010034", "Description": "Invalid Request." } ] } } ``` **Resolution** Contact CIS Implementation Manager or Mastercard Digital Support ### Authorization Failed {#authorization-failed} Returned if the Client ID has not been enabled for the MDES Customer Service API. **HTTP status code** `200` ```json { "responseId": "111111", "errors": [ { "source": "INPUT", "description": "Authorization Failed", "reasonCode": "AUTHORIZATION_FAILED", "recoverable": false } ] } ``` **Resolution** Contact your Mastercard CIS implementation manager to ensure all the necessary on-boarding steps have been completed. ### Cryptography Error {#cryptography-error} Returned when the client encryption key leveraged to encrypt the sensitive data as part of the request is either expired or is invalid This error applies to Token Activate, Token Update, Token Search. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "CRYPTOGRAPHY_ERROR", "ErrorCode": "E0010031", "Description": "Error while performing Crypto Operation - ReasonCode" } ] } } ``` **Resolution** Supply the valid value for the encryption keys as indicated in the Description ### Page Not Found {#page-not-found} Returned when the offset value in the API request is greater than total token count available for the query. This error applies to Search API. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "PAGE_NOT_FOUND", "ErrorCode": "E00100155", "Description": "The offset value in the request is greater than the total token count." } ] } } ``` **Resolution** Supply a valid value for in the offset field in the API request. ### Invalid Authorization Required Correlation ID {#invalid-authorization-required-correlation-id} The auth request correlation ID provided was invalid. This error applies to Notify Authentication Decision API. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "INVALID_AUTH_REQ_CORR_ID", "ErrorCode": "E0010165", "Description": "The auth request correlation ID provided was invalid." } ] } } ``` **Resolution** Provide a valid value in the request. ### Duplicate Request {#duplicate-request} The same request is currently being processed. This error applies to Notify Authentication Decision API. **HTTP status code** `400` ```json { "Errors": { "Error": [ { "Source": "INPUT", "ReasonCode": "DUPLICATE_REQUEST", "ErrorCode": "E0010166", "Description": "The same request is currently being processed." } ] } } ``` **Resolution** Wait for the request to be processed before trying again. ### Gateway Error Codes {#gateway-error-codes} In addition to the service, 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 the gateway, as well as resolutions to each, on the [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/) page. ## Special cases {#special-cases} In general, a HTTP 400 response is returned when an application validation error or processing error has occurred. HTTP 500 is returned for an internal service failure. * For Search and Transactions APIs, when no results are found, the response will be a HTTP 200 (success), not a HTTP 400 (error). * The response for the Token Update API of Issuer Product Configuration Id when the Id is invalid, will return HTTP '400' with the 'INVALID_FIELD_VALUE' error instead of HTTP 200 with empty XML (no explanation). * As of April 2016, for the Comments API, when no results are found, the response will be a HTTP 200 (success), not a HTTP 400 (error). * As of April 2016, the response for the Token Update API when the new account PAN is invalid or not in range as that of current PAN will return HTTP 400 with the 'INVALID_FIELD_VALUE' error instead of HTTP 200 with empty XML (no explanation). * Effective February 2025, the Token Activate API will return a [NOT_SUPPORTED](https://developer.mastercard.com/mdes-customer-service/documentation/error-codes/index.md#not-supported) error when the token has been provisioned more than 30 days prior to the activation attempt. This change replaces the previous HTTP 500 'INTERNAL_SERVICE_FAILURE' response. For further details, please consult the relevant section of the MDES Issuer Implementation Guide (MIIG) document - [Inactive Tokens](https://techdocs.mastercard.com/bundle/m_MIIG/page/MIIG_Inactive_token.html)