# Code and Formats source: https://developer.mastercard.com/payment-account-management/documentation/code-and-formats/error-codes/index.md ## Return Codes {#return-codes} All APIs return an HTTP response code of 200 if the call was successfully received and accepted for processing, with the exception of certain scenarios where a 503 HTTP response code will be returned. Any errors that subsequently occur during processing are returned in the response payload. To ensure forward-compatibility, all API client implementations must be resilient to new elements being added to outbound requests and responses from PAM. Any errors that subsequently occur during processing are returned in the response payload. 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/payment-account-management/documentation/code-and-formats/error-codes/index.md#authorization-failed) - returned from the service application and typically occur for incorrect input or cryptography errors. 2. [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/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. ## Application Error Codes {#application-error-codes} | Reason Code | Description | Detail | |-------------------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| | INVALID_JSON | Invalid JSON | The JSON could not be parsed. | | AUTHORIZATION_FAILED | Authorization failed | The request failed to present a valid cert to access the API. | | BAD_REQUEST | Duplicate requestId | Duplicate requestIds are not allowed. A 0400 HTTPS status code will be received for this particular error reason code. | | INVALID_FIELD_FORMAT | Invalid Field Format - {fieldName} | The field is not in the correct format. For instance, it should be a number but is a string. | | INVALID_FIELD_LENGTH | Invalid Field Length - {fieldName} | The value does not fall between the minimum and maximum length for the field. | | INVALID_FIELD_VALUE | Invalid Field Value - {fieldName} | The value is not allowed for the field. | | MISSING_REQUIRED_FIELD | Missing Required Field - {fieldName} | A required field is missing. | | CRYPTOGRAPHY_ERROR | Cryptography Error | There was an error decrypting the encrypted payload. | | INTERNAL_SERVICE_FAILURE | Internal Service Failure | Payment Account API had an internal exception. | | PAYMENT_ACCOUNT_REFERENCE_FOUND_FOR_NEW_ACCOUNT | Payment Account reference has already been assigned for the new card. | Payment Account reference has already been assigned for the new card. | | PAYMENT_ACCOUNT_REFERENCE_NOT_FOUND | No PAR Found | No PAR has been found for the supplied PAN or Token. | ### General Application Error format {#general-application-error-format} All the errors that the application returns follow the same data format: #### HTTP status code {#http-status-code} `200` ```json { "responseId": "", "errors": [ { "source": "INPUT", "description": "", "reasonCode": "", "recoverable": false } ] } ``` 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. ### Authorization Failed {#authorization-failed} Returned if the Client ID has not been enabled for the Payment Account Inquiry Service. **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} A cryptography error will occur when the payload has not been encrypted correctly. **HTTP status code** `200` ```json { "responseId": "111111", "errors": [ { "source": "INPUT", "description": "Cryptography Error", "reasonCode": "CRYPTOGRAPHY_ERROR", "recoverable": false } ] } ``` **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/payment-account-management/documentation/api-reference/index.md#encrypt-decrypt-configuration) **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/payment-account-management/documentation/api-reference/index.md#encrypt-decrypt-configuration) ### Invalid Field Format {#invalid-field-format} The API request contains data in a field which is incorrectly formatted. **HTTP status code** `200` ```json { "responseId": "0cc3e0fb-8d7d-4b57-8338-a3911aba4c1f", "errors": [ { "source": "INPUT", "description": "Invalid Field Format - requestId", "reasonCode": "INVALID_FIELD_FORMAT", "recoverable": false } ] } ``` ### Invalid Field Value {#invalid-field-value} The value is not allowed for the field. **HTTP status code** `200` ```json { "responseId": "123456", "errors": [ { "source": "INPUT", "description": "Invalid Field Value - oaepHashingAlgorithm", "reasonCode": "INVALID_FIELD_VALUE", "recoverable": false } ] } ``` **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/payment-account-management/documentation/api-reference/index.md) **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/payment-account-management/documentation/api-reference/index.md) ### Missing Required Field {#missing-required-field} The API request is missing a required mandatory field. **HTTP status code** `200` ```json { "responseId": "1debc552-833f-4bcb-bd3a-5f675a9102a5", "errors": [ { "source": "INPUT", "description": "Missing Required Field - requestId", "reasonCode": "MISSING_REQUIRED_FIELD", "recoverable": false } ] } ``` **Resolution** Correct the request to contain all mandatory field as described in the [API Reference](https://developer.mastercard.com/payment-account-management/documentation/api-reference/index.md) **Resolution** Correct the request to contain all mandatory field as described in the [API Reference](https://developer.mastercard.com/payment-account-management/documentation/api-reference/index.md) ### Authorization Failed {#authorization-failed-1} Returned if the Client ID has not been enabled for the Payment Account Management Service. **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. ### Invalid JSON {#invalid-json} The JSON request is incorrectly formatted. **HTTP status code** `200` ```json { "responseId": "73245138-f976-41ec-8b72-ecde27a503aa", "errors": [ { "source": "INPUT", "description": "Invalid JSON", "reasonCode": "INVALID_JSON", "recoverable": false } ] } ``` **Resolution** Check the message is a correctly formatted JSON and resubmit. ## requestStatus Return Codes {#requeststatus-return-codes} The return codes which will be provided by the consuming systems as part of the [**requestStatus**](https://developer.mastercard.com/payment-account-management/documentation/api-reference/index.md#request-status) response are detailed below. The 0100 Error codes are associated with ABU, the 0200 Error codes are associated with the Token Vault, and the 0300 Error codes are associated with the PAR Vault. **HTTP status code** `200` ```json { "statuses": [ { "requestId": "123456", "services": [ { "serviceName": "PAN_PAR_Mapping", "status": "FAILURE", "additionalInformation": 302 } ] } ] } ``` **Resolution** Please refer to the tables below for specific resolutions for each service name. ### PAR Vault {#par-vault} | Error Code | Description | Recommendation | |------------|-------------------------------------------|-----------------------------------------| | 301 | Invalid Request | Do not resubmit | | 302 | Record not found with old Account Number | Check supplied card number and resubmit | | 303 | PAR Operation Failed | Do not resubmit | | 304 | PAR already exists for new Account Number | Do not resubmit | | 305 | Not PAR eligible | Do not resubmit | ### Token Vault {#token-vault} | Error Code | Description | Recommendation | |------------|-------------------------------------------------------------------|----------------------------| | 201 | Input Validation error on Token Vault | Verify Inputs and resubmit | | 202 | Token Delete operation Failed | Do not resubmit | | 203 | Token Update operation Failed | Do not resubmit | | 204 | No Active or suspended Tokens found for given account information | Do not resubmit | ### ABU {#abu} | Error Code | Description | Recommendation | |------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | 100 | Account override for delete request, but not on Mastercard files | Do not resubmit | | 101 | Old Account Number is not numeric | Provide numeric account number and resubmit | | 102 | Old Account Number is not valid length | Correct old account number length and resubmit | | 104 | New Account Number is not numeric | Provide numeric value for new account number and resubmit | | 105 | New Account Number not valid length | Correct new account number length and resubmit | | 107 | New Account Number is not in the issuer BIN range | Do not resubmit | | 108 | Old Expiration Date is invalid | Correct old expiration date and resubmit | | 109 | New Expiration Date is invalid | Correct new expiration date and resubmit | | 110 | Invalid Reason Code or Invalid Header or Detail Record ID | Correct reason code or header and resubmit | | 111 | Issuer's customer ID/ICA number not an active issuer ID on Mastercard records | Correct ID/ICA number and resubmit | | 112 | Issuer's customer ID/ICA number is valid only for acquirer customer | Do not resubmit | | 113 | Old Account Number exists in Mastercard database | Do not resubmit | | 114 | New Account Number exists in Mastercard database | Do not resubmit | | 118 | Old Account Number is not in Mastercard database | Do not resubmit | | 119 | New Account Number is not in Mastercard database | Do not resubmit | | 120 | Old Account Number is not in the issuer BIN range for an Initial Load() | Do not resubmit | | 121 | Old Account Number and New Account Number are not the same for an Expiration Date | Ensure old and new account number match for expiration date change and resubmit | ## Gateway Errors {#gateway-errors} Refer to [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/)