# Code and Formats source: https://developer.mastercard.com/commercial-connect-api/documentation/code-and-formats/index.md ## HTTP Response Codes/Reason Codes {#http-response-codesreason-codes} The most common expected response codes for the supported HTTP methods are as follows: | HTTP Response Code | Response Description | |----------------------------|-------------------------------------------------------------------------------------------------------------------------| | 200 (OK) | The request was completed successfully. | | 201 (CREATED) | Successful creation occurred using a POST request. | | 204 (NO CONTENT) | Successful update occurred using a PUT request. | | 400 (BAD REQUEST) | General error when the request could not be fulfilled due to errors such as validation errors or missing required data. | | 401 (UNAUTHORIZED) | Missing or invalid authentication token. | | 403 (FORBIDDEN) | The user has insufficient permissions to a resource or action. | | 404 (NOT FOUND) | The requested resource was not found. | | 422 (UNPROCESSABLE ENTITY) | Resource already exists / Resource has been modified. | ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by the Mastercard Commercial Connect 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 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} Mastercard returns errors in the following structure. ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` ## Mastercard Commercial Connect API Error Codes {#mastercard-commercial-connect-api-error-codes} ### Request Validation Errors {#request-validation-errors} | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| | 400 | REQUIRED_FIELD | The field '%s' is required. | Provide the required field. | | 400 | REQUIRED_QUERY_PARAM | Query parameter '%s' is required. | Provide the required parameter. | | 400 | INVALID_LENGTH | The value in the field '%s' does not meet the required length range. Current length: 32 Minimum allowed: 1. Maximum allowed: 30. | Set a valid length. | | 400 | INVALID_SIZE | The array in the field '%s' does not meet the required size range. Current size: 4 Minimum allowed: 0, Maximum allowed: 3. | Set a valid size. | | 400 | EMPTY_STRING | The field '%s' cannot be empty. | Provide required data. | | 400 | INVALID_PATTERN | The value in the field '%s' does not match the required pattern. Required Pattern: '\^\[0-9\]{4}-(0\[1-9\]1\[012\])-(0\[1-9\]\[12\]\[0-9\]3\[01\])$'. | Provide the value in the required pattern. | | 400 | BELOW_RANGE | The value of field '%s' is below the required range. Minimum value: 4. | Set a valid value. | | 400 | ABOVE_RANGE | The value of field '%s' is above the required range. Maximum value: 4. | Set a valid value. | | 400 | UNRECOGNIZED_FIELD | The field '%s' is not recognized. | Provide a valid field. | | 400 | DUPLICATE_FIELD | Duplicate field '%s'. | Provide a valid field. | | 400 | INVALID_DATA | The data format or type in field '%s' is not valid. Verify the data format and type. | Set a valid type or format. | | 400 | BAD_REQUEST | The request body is not valid. Verify the request format. | Provide a valid format. | | 400 | INVALID_DATE | The value of field '%s' does not meet the required date format. The valid date format is 'yyyy-MM'. | Set a valid format. | | 400 | FUTURE_DATE | The value of field '%s' does not meet the required date range. Only future dates are allowed. | Set a valid format. | | 400 | READONLY_FIELD | The field '%s' is read-only and must not be provided. | Remove the read-only field from the payload. | Error codes associated with specific endpoints are listed below. ### Real Cards {#real-cards} **Register a real card.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|-------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------| | 400 | INVALID_CARD_CONTACT | Invalid card contact information. Provide at least one valid contact detail. | Provide at least one valid contact detail. | | 400 | INVALID_CONTROLS_DATA | The card control is not valid. Verify the controls format and type. | Provide valid card controls. | | 400 | INVALID_CONTROLS_AMOUNT | The card control is not valid. At least one spend limit must be defined. | Provide a defined spend limit. | | 400 | DUPLICATE_CARD_NUMBER | The card number is already present. Duplicate card numbers are not allowed. | Provide a valid card number. | | 400 | INVALID_CARD_NUMBER | The card number is invalid. | Provide a valid card number. | | 400 | INVALID_CARD_NUMBER_BIN_RANGE | The card number does not fall within the allowed BIN range. | Provide a valid card number. | | 400 | INVALID_ENTITY_ID | The value of `entityId` is not valid. | Provide A valid `entityId`. | | 400 | UNAUTHORIZED_ISSUER | The issuer is not authorized. | Provide a valid card number within the allowed bin range. | **Partial success (201)** | Warning Reason Code | Warning Description (Example) | How to Resolve | | |-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|--------------------------------|---| | INVALID_COUNTRY_CODE | The country code is not valid. | Provide a valid country code. | | | INVALID_CONTROLS_AMOUNT | The card control is not valid. At least one spend limit must be defined. | Provide a defined spend limit. | | | INVALID_CONTROLS_TRANSACTION_AMOUNT | The transaction count set for a smaller scope should be less than or equal to the transaction count set for a larger scope. | Provide a valid value. | | | INVALID_MCC_CONTROL | The MCC control is invalid. | Provide a valid value. | | | INVALID_END_DATE | The validity period does not meet the required date range. Start date must be before end date. | Provide a valid end date. | | | FUTURE_DATE | The validity period does not meet the required date range. Only future dates are allowed. | Provide a valid date. | | **Retrieve real card details for existing real card.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|---------------------|---------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | **Search real card account details.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------------------|------------------------------------------------------------------------------|------------------------| | 400 | INVALID_REAL_CARD_SEARCH_REQUEST | `cardNumber` must have a valid value. | Provide a valid value. | | 400 | required.parameters.not.present | Non-corporate users, one of the \[corpGuids, issuerGuids\] must be provided. | Provide a valid value. | **Update real card details.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|--------------------------------------|----------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | BLOCKED_REAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Add real card controls.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------| | 400 | INVALID_CONTROLS_AMOUNT | The card control is not valid. At least one spend limit must be defined. | Provide a defined spend amount. | | 400 | INVALID_COUNTRY_CODE | Country code is not valid. | Provide a valid Country Code. | | 400 | INVALID_CONTROLS_AMOUNT | The spend amount set for a smaller scope should be less than or equal to the spend amount set for a larger scope. | Provide a valid value. | | 400 | INVALID_CONTROLS_TRANSACTION_COUNT | The transaction count set for a smaller scope should be less than or equal to the transaction count set for a larger scope. | Provide a valid value. | | 400 | INVALID_MCC_CONTROL | The MCC control is not valid. | Provide a valid MCC value. | | 400 | INVALID_END_DATE | The validity period does not meet the required date range. Start date must be before end date. | Provide a valid value. | | 400 | FUTURE_DATE | The validity period does not meet the required date range. Only future dates are allowed. | Provide a valid value. | | 404 | RESOURCE_NOT_FOUND | Real card resource not found. | Provide valid data. | | 422 | BLOCKED_REAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Update real card controls.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------| | 400 | INVALID_CONTROLS_AMOUNT | The card control is not valid. At least one spend limit must be defined. | Provide a defined spend amount. | | 400 | INVALID_COUNTRY_CODE | Country code is not valid. | Provide a valid Country Code. | | 400 | INVALID_CONTROLS_AMOUNT | The spend amount set for a smaller scope should be less than or equal to the spend amount set for a larger scope. | Provide a valid value. | | 400 | INVALID_CONTROLS_TRANSACTION_COUNT | The transaction count set for a smaller scope should be less than or equal to the transaction count set for a larger scope. | Provide a valid value. | | 400 | INVALID_MCC_CONTROL | The MCC control is not valid. | Provide a valid MCC value. | | 400 | INVALID_END_DATE | The validity period does not meet the required date range. Start date must be before end date. | Provide a valid value. | | 400 | FUTURE_DATE | The validity period does not meet the required date range. Only future dates are allowed. | Provide a valid value. | | 404 | RESOURCE_NOT_FOUND | Real card resource not found. | Provide valid data. | | 422 | BLOCKED_REAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Delete real card controls.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|--------------------------------------|----------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | BLOCKED_REAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Add real card contacts.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------| | 400 | INVALID_CARD_CONTACT | Invalid card contact information. | Provide at least one valid contact detail. | | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | UNPROCESSABLE_ENTITY | Card contact is already present. Multiple card contacts are not allowed. | Use the update real card contact endpoint to update existing card contact. | | 422 | BLOCKED_REAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Update real card contacts.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------|------------------------------------------------------------------------------|------------------------------------| | 400 | INVALID_CARD_CONTACT | Invalid card contact information. Provide at least one valid contact detail. | Provide valid contact information. | | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | UNPROCESSABLE_ENTITY | Associated card contact not found. | Provide a valid card contact. | **Delete real card contacts.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|------------------------------------|-------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | RESOURCE_NOT_FOUND | Associated card contact not found. | Provide a valid card contact. | **Update real card status.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|-----------------------------------------------------------------------------------------------|----------------------------------------------------------| | 400 | INVALID_STATUS | The value of `accountStatus` is not valid. The `accountStatus` must be 'ACTIVE' or 'BLOCKED'. | Use one of the accepted valid values: ACTIVE or BLOCKED. | | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | INVALID_STATUS | The real card already has the specified status. | Provide valid data. | **Replace real card.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|-------------------------------|-----------------------------------------------------------------------------|-----------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 400 | DUPLICATE_CARD_NUMBER | The card number is already present. Duplicate card numbers are not allowed. | Provide a valid card number. | | 400 | INVALID_CARD_NUMBER | The real card number provided is invalid. | Provide a valid Real cardNumber. | | 400 | INVALID_CARD_NUMBER_BIN_RANGE | The card number does not fall within the allowed BIN range. | Provide a valid Real cardNumber. | | 400 | INVALID_ENTITY_ID | The value of `entityId` is not valid. | Provide valid data. | | 400 | UNAUTHORIZED_ISSUER | Unauthorized issuer. | Provide a valid card number within the allowed bin range. | | 400 | INVALID_CARD_NUMBER | The real card number provided is invalid. | Provide a new card number. | | 422 | BLOCKED_REAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Delete real card.** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|---------------------|-------------------------------------------------------------------------|--------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | VIRTUAL_CARD_EXISTS | The real card has virtual cards associated to it and cannot be deleted. | Delete associated virtual cards to perform the action. | ### Virtual Cards {#virtual-cards} **Create a virtual card** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------| | 400 | INVALID_CONTROLS_AMOUNT | The card control is not valid. At least one spend limit must be defined. | Provide a defined spend limit. | | 400 | INVALID_COUNTRY_CODE | Country code is not valid. | Provide a valid Country Code. | | 400 | INVALID_CONTROLS_AMOUNT | The spend amount set for a smaller scope should be less than or equal to the spend amount set for a larger scope. | Provide a valid limit. | | 400 | INVALID_CONTROLS_TRANSACTION_COUNT | The transaction count set for a smaller scope should be less than or equal to the transaction count set for a larger scope. | Provide a valid limit. | | 400 | INVALID_MCC_CONTROL | MCC control is not valid. | Provide a valid value. | | 400 | INVALID_END_DATE | The validity period does not meet the required date range. | Set an end date that is later than the start date. | | 400 | FUTURE_DATE | The validity period does not meet the required date range. Only future dates are allowed. | Provide a valid value. | | 422 | RESOURCE_NOT_FOUND | Real card resource not found. | Provide valid data. | | 422 | BLOCKED_VIRTUAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Retrieve virtual card details** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|---------------------|---------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | **Search virtual card details** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|-------------------------------------|-------------------------------------------------------------------|------------------------| | 400 | INVALID_VIRTUAL_CARD_SEARCH_REQUEST | `realCardid` or `cardNumber` must have a valid value. | Provide a valid value. | | 400 | INVALID_VIRTUAL_CARD_SEARCH_REQUEST | `realCardid` or `cardNumber` cannot be searched at the same time. | Provide a valid value. | **Update virtual card status** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|-----------------------------------------------------------------------------------------------|----------------------------------------------------------| | 400 | INVALID_STATUS | The value of `accountStatus` is not valid. The `accountStatus` must be 'ACTIVE' or 'BLOCKED'. | Use one of the accepted valid values: ACTIVE or BLOCKED. | | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | INVALID_STATUS | The virtual card already has the specified status. | Provide a valid value. | **Update virtual card details** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------|-----------------------------------------------------|-------------------------------------------------------------| | 400 | INVALID_DATE | The card must be valid for between 0 and 24 months. | Set an expiry date to be between 1 and 24 months. | | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | BLOCKED_VIRTUAL_CARD | Virtual card is in a blocked state. | Update virtual card status to ACTIVE to perform the action. | **Update virtual card controls** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------| | 400 | INVALID_CONTROLS_AMOUNT | The card control is not valid. At least one spend limit must be defined. | Provide a defined spend limit. | | 400 | INVALID_COUNTRY_CODE | Country code is not valid. | Provide a valid Country Code. | | 400 | INVALID_CONTROLS_AMOUNT | The spend amount set for a smaller scope should be less than or equal to the spend amount set for a larger scope. | Provide a valid limit. | | 400 | INVALID_CONTROLS_TRANSACTION_COUNT | The transaction count set for a smaller scope should be less than or equal to the transaction count set for a larger scope. | Provide a valid limit. | | 400 | INVALID_MCC_CONTROL | MCC control is not valid. | Provide a valid value. | | 400 | INVALID_END_DATE | The validity period does not meet the required date range. | Set an end date that is later than the start date. | | 400 | FUTURE_DATE | The validity period does not meet the required date range. Only future dates are allowed. | Provide a valid value. | | 422 | RESOURCE_NOT_FOUND | Real card resource not found. | Provide valid data. | | 422 | BLOCKED_VIRTUAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | **Add virtual card data** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | BLOCKED_VIRTUAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | | 422 | UNPROCESSABLE_ENTITY | Card data is already present. Duplicate card data is not allowed. | Use the Update virtual card data endpoint to update existing card data. | **Update virtual card data** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------|--------------------------------------|----------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 422 | BLOCKED_VIRTUAL_CARD | The real card is in a blocked state. | Update real card status to ACTIVE to perform the action. | | 422 | RESOURCE_NOT_FOUND | Associated card data not found. | Provide valid card data. | **Delete virtual card data** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|----------------------|-------------------------------------|-------------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | | 404 | RESOURCE_NOT_FOUND | Associated card data not found. | Provide valid card data. | | 422 | BLOCKED_VIRTUAL_CARD | Virtual card is in a blocked state. | Update virtual card status to ACTIVE to perform the action. | **Delete virtual card** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|---------------------|---------------------| | 404 | RESOURCE_NOT_FOUND | Resource not found. | Provide valid data. | ### Authorization Report Error Codes {#authorization-report-error-codes} **Generate an authorization report** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------------|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | INVALID_DATE_RANGE | The field `endDate` must not be before the field `startDate`. | Provide valid data. | | 400 | INVALID_REPORT_CARD_TYPE | The value of `cardType` is not valid. The cardType must be 'REAL' or 'VIRTUAL'. | Provide valid data. | | 404 | RESOURCE_NOT_FOUND | Account not found. | Provide a valid virtual `accountId` or a valid real card `accountId`. | | 404 | RESOURCE_NOT_FOUND | Real card resource not found. | Provide a valid real card `accountId`. | | 422 | INVALID_DATE_RANGE | Report date range cannot exceed 30 days(s). | Provide a valid value. | | 422 | INVALID_STATUS | Activity status is invalid. | Provide a valid activity status. Valid status are ALL, APPROVED, PARTIAL_APPROVED, DECLINED, ISSUER_DECLINED, REQUEST_RESPONSE, ADVICE_RESPONSE, REVERSAL_RESPONSE. | **Get the authorization report status** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|--------------------------------------------------|-----------------------------------------------------------------------| | 400 | INVALID_REPORT_ID | The value in the field `report_id` is not valid. | Provide valid data. | | 404 | RESOURCE_NOT_FOUND | Report ID is not found. | Provide a valid virtual `accountId` or a valid real card `accountId`. | **Get the authorization report data** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|--------------------------------------------------|-----------------------------------------------------------------------| | 400 | INVALID_REPORT_ID | The value in the field `report_id` is not valid. | Provide valid data. | | 400 | LIMIT_ABOVE_RANGE | The limit value should not exceed 100. | Provide a valid value. | | 404 | RESOURCE_NOT_FOUND | Report ID is not found. | Provide a valid virtual `accountId` or a valid real card `accountId`. | | 422 | REPORT_IN_PROGRESS | Report generation is in progress. | Retry after status is COMPLETED. | ### Clearing Report Error Codes {#clearing-report-error-codes} **Generate a clearing report** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------------|---------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | 400 | INVALID_DATE_RANGE | The field `endDate` must not be before the field `startDate`. | Provide valid data. | | 400 | INVALID_REPORT_CARD_TYPE | The value of `cardType` is not valid. The cardType must be 'REAL' or 'VIRTUAL'. | Provide valid data. | | 404 | RESOURCE_NOT_FOUND | Account not found. | Provide a valid virtual `accountId` or a valid real card `accountId`. | | 404 | RESOURCE_NOT_FOUND | Real card resource not found. | Provide a valid real card `accountId`. | | 422 | INVALID_DATE_RANGE | Report date range cannot exceed 30 days(s). | Provide a valid value. | | 422 | INVALID_STATUS | Activity status is invalid. | Provide a valid activity status. Valid status are ALL, PRESENTMENT, SECOND_PRESENTMENT, CHARGEBACK, ARBITRATION_CHARGEBACK. | **Get the clearing report status** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|--------------------------------------------------|---------------------| | 400 | INVALID_REPORT_ID | The value in the field `report_id` is not valid. | Provide valid data. | | 404 | RESOURCE_NOT_FOUND | Report ID is not found. | Provide valid data. | **Get the clearing report data** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|--------------------------------------------------|-----------------------------------------------------------------------| | 400 | INVALID_REPORT_ID | The value in the field `report_id` is not valid. | Provide valid data. | | 400 | LIMIT_ABOVE_RANGE | The limit value should not exceed 100. | Provide a valid value. | | 404 | RESOURCE_NOT_FOUND | Report ID is not found. | Provide a valid virtual `accountId` or a valid real card `accountId`. | | 422 | REPORT_IN_PROGRESS | Report generation is in progress. | Retry after status is COMPLETED. | ### Payment Initiation Error Codes {#payment-initiation-error-codes} **Post payment initiations** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | CARD_EXPIRATION_REQUIRED | The `cardExpiration` field is required when including the cardNumber. | Provide the cardExpiration field when including the cardNumber in the request. | | 400 | CARD_CVC_REQUIRED | The field `cvc` is required when including the cardNumber. | Provide the CVC (Card Verification Code) when including the cardNumber in the request. | | 400 | CARD_TYPE_REQUIRED | The field `cardType` is required when including the accountId. | Provide the `cardType` field when including the accountId in the request. | | 400 | INVALID_PAYMENT_CARD_TYPE | The `cardType` value is not valid. The `cardType` must be 'VIRTUAL'. | Set the `cardType` to 'VIRTUAL' because this operation applies only to virtual cards. | | 400 | NO_ACCOUNTS | Neither the existing card nor the new card is provided. At least one card type must be specified. | Provide either `existingCard` or `newCard` details in the request. | | 400 | MULTIPLE_ACCOUNT_IDENTIFIERS | Both the accountId and the cardNumber are provided. Only one account identifier is allowed. | Remove either the `accountId` or the `cardNumber` from the request. Provide only one account identifier. | | 400 | NO_ACCOUNT_IDENTIFIER | Neither the `accountId` nor the `cardNumber` is provided. At least one account identifier is required. | Provide either the `accountId` or the `cardNumber` to identify the account. | | 400 | MULTIPLE_ACCOUNTS | Both the existing card and the new card are provided. Only one card type is allowed. | Remove either the `existingCard` or the `newCard` from the request. Provide only one card type. | | 400 | MULTIPLE_CREDITOR_IDENTIFICATION | Both the `supplierId` and the e-mail are provided. Only one creditor identification method is allowed. | Remove either the `supplierId` or the email from the request. Provide only one creditor identification method. | | 400 | MISSING_DEBTOR_NAME | The debtor name is missing. | Provide a debtor name with a maximum of 140 characters. | | 400 | INVALID_DEBTOR_ID | The debtor ID is not valid or does not exist. | Provide a valid debtor ID. | | 400 | INVALID_DEBTOR_DETAILS | The debtor identification details are invalid. | Provide a valid debtor identification. | | 400 | NOT_ASSOCIATED_DEBTOR_ID | The `debtorId` included in the request is not associated with this debtor agent. | Provide a `debtorId` that is associated with your debtor agent. | | 400 | NO_DEBTOR_ADDRESS | The debtor postal address details are missing. | Add the `postalAddress` object with country and postalCode. | | 400 | INVALID_CARD_NUMBER | The card number is invalid. | Provide a valid card number. | | 400 | INVALID_SUPPLIER_ID | The supplier ID is not valid or does not exist. | Provide a valid supplier ID. | | 400 | INVALID_SUPPLIER_IDENTIFICATION | The supplier identification details are invalid. | Provide valid supplier identification details. | | 400 | INACTIVE_SUPPLIER | The identified supplier is not actively accepting carded payments. | Contact the supplier. | | 400 | INVALID_SUPPLIER_EMAIL | The supplier email is invalid. | Provide the valid supplier email in the correct format ([user@domain.tld](mailto:user@domain.tld)). | | 400 | INVALID_CREDITOR_REFERENCE_TYPE | The provided creditor reference type code is invalid. | Provide one of the following creditor reference type codes: * DISP: DispatchAdvice * FXDR: ForeignExchangeDealReference * PUOR: PurchaseOrder * RPIN: RelatedPaymentInstruction * RADM: RemittanceAdviceMessage * SCOR: StructuredCommunicationReference | | 400 | NO_CREDITOR_IDENTIFICATION | The creditor identification details are missing. | Add the identification object in the creditor. | | 400 | NO_PAY_AMOUNT_VALUE | Enter an instructed amount for the transaction. | Provide an instructed amount for the transaction. | | 400 | INVALID_INSTRUCTED_AMT | The instructed amount is invalid. The instructed amount reconciliation error. | Verify that the instructed amount equals the sum of remitted amounts. | | 400 | INVALID_AMOUNT_TYPE | The remittance amount type code is missing or invalid. | Provide one of the following remittance amount type codes: * APDS - AdditionalPromotionalDiscount * STDS - StandingDiscount * TMDS - TermsDiscount * CREN - CreditNote * CITY - CityTax * CNTY - CountyTax * LOCL - LocalTax * PROV - ProvinceTax * STAT - StateTax * DUPA - DuePayable * REMI - Remitted | | 400 | NO_CURRENCY | The currency is missing. | Add the currency field in the required amount object. | | 400 | INVALID_CURRENCY_CODE | The currency code is invalid. | Use a valid currency code (ex. USD) in `FieldName`. Use valid ISO 4217 3-letter currency code (e.g., USD, EUR) | | 400 | INVALID_CURRENCY | The provided currency code is invalid. | Provide a valid three character currency code. | | 400 | MISMATCHED_CURRENCY | The instructed currency and referred currency do not match. | Ensure all amounts use the same currency. | | 400 | NO_ADJUSTMENT_AMOUNT_CURRENCY | The adjusted amount currency is missing. | Add currency in the adjustment amount. | | 400 | INVALID_CARD_NUMBER | The card number is invalid. | Provide a valid card number. | | 400 | REQUESTED_EXECUTION_DATE_AFTER_CARD_EXPIRATION | The requested execution date is after the card's expiration date. | Set the `requestedExecutionDate` to be before the date set in `cardExpiration`. Note that the `requestedExecutionDate` must be before the 1st day of the month following the month listed in the `cardExpiration`. | | 400 | EXPIRED_CARD | The card has expired. | Use a card with a future expiration date. | | 400 | INVALID_REQUESTED_EXECUTION_DATE | Enter a valid request execution date. Requested execution date must be in numerical YYYY-MM-DD format. | Use the YYYY-MM-DD format for the `requestedExecutionDate`. | | 400 | REQUESTED_EXECUTION_DATE_OUT_OF_RANGE | Enter a valid request execution date. The requested execution date must not be in the past. | Ensure that the date is not in the past and is within an acceptable range. | | 400 | INVALID_PAYMENT_DUE_DATE | The payment due date is invalid. | Use a valid date in the YYYY-MM-DD format for payment due date. | | 400 | INVALID_RELATED_DATE_TYPE | The entered related date type code is invalid. | Use a valid related date type code from the approved list. | | 400 | NO_RELATED_DATE_TYPE | Enter a valid related date type code. | Add `relatedDate.type.code` in the referred document. | | 400 | INVALID_REMITTANCE_INFO | The remittance information structure is invalid or missing. | Provide 'remittanceInfo' with a valid structure. | | 400 | INVALID_REMITTANCE_INFO_STRUCTURED_ELEMENTS | Structured elements remittance information is invalid or missing. | Provide the valid structured elements in the `remittanceInfo.structuredElements` array. | | 400 | LIMIT_EXCEEDED_UNSTRUCTURED_ELEMENTS | Unstructured elements exceed the limit of 30 items. | Reduce unstructured elements to a maximum of 30 items. | | 400 | INVALID_UNSTRUCTURED_ELEMENTS | Invalid unstructured elements length or format. | Ensure that unstructured elements are 1-140 characters in length and are appropriately formatted. | | 400 | INVALID_REMITTANCE_LOCATION_DETAILS_METHOD | Invalid or missing remittance location details method code. | Provide one of the following accepted method codes: * FAXI - FAX * EDIC - Electronic Data Interchange * URID - Uniform Resource Identifier * EMAL - Email * POST - Post * SMSM - SMS | | 400 | INVALID_REMITTANCE_LOCATION_DETAILS_NAME | Invalid or missing remittance location name. | Ensure remittance location name is 1-140 characters long. | | 400 | INVALID_REMITTANCE_LOCATION_DETAILS_ADDRESS | Invalid or missing remittance location address. | Provide an address in the related remittance location. | | 400 | INVALID_REFERRED_DOC_INFO_SIZE | The `referredDocInfo` array does not meet the the required size range. Current size: {}. Minimum allowed: 0. Maximum allowed: 2. | Set a valid size for the array between 0 and 2 items. | | 400 | MISSING_REFERRED_DOC_INFO_TYPECODE | The typeCode is missing in the `referredDocInfo` array. | Provide a valid document type code: * CINV - Commercial Invoice * POUR - Purchase Order (this is a supporting document and can be only added as an attachment along with a CINV) * CREN - Credit Note * BREF - Booking Reference * CLAM - Claim Document | | 400 | INVALID_REFERRED_DOC_INFO_TYPE_CODE | The provided typeCode is not valid. | Provide a valid document type code: * CINV - Commercial Invoice * POUR - Purchase Order (this is a supporting document and can be only added as an attachment along with a CINV) * CREN - Credit Note * BREF - Booking Reference * CLAM - Claim Document | | 400 | INVALID_REFERRED_DOC_INFO_TYPE_CODE_USED | The POUR typeCode provided can only be used in combination with typeCode = CINV. | Remove POUR or provide a document with typeCode = CINV. | | 400 | MISSING_INVOICE_TYPE_CODE | The provided typeCodes do not include either CINV or CREN. | Provide at least one of the following document type codes: * CINV - Commercial Invoice * CREN - Credit NoteRemove POUR or provide a document with typeCode = CINV. | | 400 | MISSING_REFERRED_DOC_AMOUNT | The `referredDocAmount` array is empty. | Provide amounts in the `referredDocAmount` array. | | 400 | INVALID_REFERRED_DOC_AMOUNTS_REMI | The amount of typeCode = REMI is invalid because it does not equal the sum of the line item amounts. | Provide an amount that equals the sum of the line item amounts. | | 400 | MISSING_REFERRED_DOC_INFO_TYPE_CODE_CINV | No document with type commercial invoice (CINV) is provided. | Provide at least one CINV document. | | 400 | MISSING_REFERRED_DOC_INFO_DOC_ID | The `docId` is missing. | Provide a `docId` that is 1-35 characters long. | | 400 | INVALID_REFERRED_DOC_INFO_DOC_ID | The value in the `docId` field must be a string. | Provide a docId in string format. | | 400 | INVALID_LENGTH_REFERRED_DOC_INFO_DOC_ID | The value in the `docId` field does not meet the required length range. Current length: {}. Minimum allowed: 1. Maximum allowed: 35. | Set a valid length for `docId` between 1 and 35 characters. | | 400 | MISSING_LINE_DETAILS_LINE_ID | The `lineId` is missing. | Provide a `lineId` that is 1-35 characters long. | | 400 | INVALID_LINE_DETAILS_LINE_ID | The value in the `lineId` field must be a string. | Provide a lineId in a string format. | | 400 | MISSING_LINE_DETAILS_AMOUNT | The due payable amount is missing in the line detail \[ {lineId} \]. | Provide an amount in the due payable line details item. | | 400 | INVALID_LINE_DETAILS_AMOUNT | The line details remitted amount is invalid. | Verify that line details remitted amounts add correctly. | | 400 | MISSING_REFERRED_DOC_AMOUNT_TYPE_TAX | The `referredDocAmount` is missing a tax amount. | Provide an amount with one of the following typeCodes: * CITY - City Tax * CNTY - County Tax * LOCL - Local Tax * PROV - Province Tax * STAT - State Tax * TAXS - Tax * STAX - Self-assessed Tax | | 400 | NO_TOTAL_TAX_AMOUNT | Enter a total tax amount. A tax amount is found in remittance data. | Add the `totalTaxAmount` if you've added tax amounts as part of remittance data. | | 400 | INVALID_TOTAL_TAX_AMOUNT | Enter a valid total tax amount. There was a total tax amount reconciliation error. | Ensure that the `totalTaxAmount` equals the sum of all tax amounts. | | 400 | MISSING_ADJUSTMENT_AMOUNTS_AMOUNT | The amount is missing in the `adjustmentAmounts` array. | Provide an amount in the `adjustmentAmounts` array. | | 400 | MISSING_ADJUSTMENT_AMOUNTS_REASON | The reason is missing in the `adjustmentAmounts` array. The reason is required whenever an adjustment amount is provided. | Provide a valid reason: * INCORRECT_AMOUNT - The invoice amount is incorrect. * DISC_EARLY_PAY - Discount applied for early payment. * DISC_TAX_EXEMPT - Discount applied for tax exemption. * DISC_SALES - Discount given by a salesperson. * DAMAGED_GOODS - Discount applied for damaged goods. * LATE_GOODS - Discount applied for late delivery of goods. * LATE_SERVICE - Discount applied for late services. * FEES - Additional fees applied for convenience or payment processing. * PREV_PAY_AMT - There was a previous payment made to reduce the balance of the invoice total. * PARTIAL_PAY - This is a partial payment. The total invoice is being paid by more than one transaction | | 400 | INVALID_ADJUSTMENT_AMOUNTS_REASON | The provided reason is not valid. | Provide a valid reason: * INCORRECT_AMOUNT - The invoice amount is incorrect. * DISC_EARLY_PAY - Discount applied for early payment. * DISC_TAX_EXEMPT - Discount applied for tax exemption. * DISC_SALES - Discount given by a salesperson. * DAMAGED_GOODS - Discount applied for damaged goods. * LATE_GOODS - Discount applied for late delivery of goods. * LATE_SERVICE - Discount applied for late services. * FEES - Additional fees applied for convenience or payment processing. * PREV_PAY_AMT - There was a previous payment made to reduce the balance of the invoice total. * PARTIAL_PAY - This is a partial payment. The total invoice is being paid by more than one transaction. | | 400 | MISSING_ADJUSTMENT_AMOUNTS_CREDIT_DEBIT_INDICATOR | The `creditDebitIndicator` is missing in the `adjustmentAmounts` array. | Provide a valid `creditDebitIndicator`: * CRDT - Credit Operation * DBIT - Debit Operation | | 400 | INVALID_ADJUSTMENT_AMOUNTS_CREDIT_DEBIT_INDICATOR | The `creditDebitIndicator` is invalid in the `adjustmentAmounts` array. | Provide a valid `creditDebitIndicator`: * CRDT - Credit Operation * DBIT - Debit Operation | | 400 | INVALID_CHARGE_TYPE | Enter a valid charge type. The provided value does not match the valid value list. | Use a valid charge type from the approved value list. | | 400 | INVALID_BIC | Invalid BIC ID length or format. | Provide a BIC Id that is 8-11 characters long in the following format pattern: \[A-Z0-9\]{4,4}\[A-Z\]{2,2}\[A-Z0-9\]{2,2}(\[A-Z0-9\]{3,3}){0,1}. | | 400 | INVALID_LEI | Invalid LEI ID length or format. | Provide an LEI ID that is 1-20characters long in the following format pattern: \[A-Z0-9\]{18,18}\[0-9\]{2,2}. | | 400 | MISSING_INVOICER_IDENTIFICATION | Missing invoicer identification. | Provide a BIC or LEI to identify the invoicer. | | 400 | MISSING_INVOICEE_IDENTIFICATION | Missing invoicee identification. | Provide a BIC or LEI to identify the invoicee. | | 400 | INVALID_ENDTOENDID | Missing or invalid end to end ID. | Ensure end to end ID is 1-35 characters long. | | 400 | UNSUPPORTED_PAYMENT_SCHEDULE | The creditor agent does not support future-dated payments at this time. | Configure the payment date to be on the present day or prior. | | 400 | LINK_REQUIRED | A supplier link is required for payment but is not configured. | Ensure the target creditor for the payment exists and is properly configured. | | 400 | INVALID_PAYMENT_CONTROLS_DECISION | The payment controls decision state is not valid for payment initiation. | Ensure the target creditor for the payment exists and is properly configured. | **Get payment status** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|-------------------|---------------------------|---------------------------| | 400 | INVALID_BPA_ICA | `bpaICA` is not valid. | Provide a valid `bpaICA`. | | 400 | INVALID_PAYMENTID | `paymentId` is not valid. | Provide a valid value. | ### Entity Hierarchy Error Codes {#entity-hierarchy-error-codes} **Get the API user's entity identifier** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|--------------------|---------------------------------------------|----------------------------------| | 404 | RESOURCE_NOT_FOUND | Entity resource not found. | Provide a valid entity resource. | | 403 | FORBIDDEN_USER | The action is forbidden for the given user. | Provide a valid user. | **Get the entity identifiers of all the descendants of a given entity** | HTTP Code | Reason Code | Description | How to Resolve | |-----------|---------------------------------|----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| | 404 | RESOURCE_NOT_FOUND | Entity resource not found. | Provide a valid entity resource. | | 400 | INVALID_DESCENDANT_TYPE | The value of `descendantType` is not valid. Accepted values are: COMPANY, COMPANY_GROUP, ISSUER, ISSUER_GROUP. | Provide one of the accepted values. | | 400 | INVALID_DESCENDANT_STATUS | The value of `descendantStatus` is not valid. Accepted values are: ACTIVE, INACTIVE. | Provide one of the accepted values. | | 400 | INVALID_DESCENDANT_ICA_LENGTH | The value of `descendantIca` does not meet the required length range. Minimum allowed: 4, Maximum allowed: 11. | Provide a valid length range. | | 400 | INVALID_CREATED_DATE_TIME_ORDER | Invalid date range. `createdDateBefore` must represent a later point in time than `createdDateAfter`. | Provide a valid date range. | | 400 | INVALID_ENTITY_TYPE | No descendants are associated with this entity type and entity ID. | Provide a valid entity type or entity ID to get descendants when using this filter criteria. | | 400 | INVALID_PARENT_ENTITY | No descendants are associated with this parent entity. | Provide a valid parent entity to get descendants when using this filter criteria. |