Jp Morgan Wallet

Errors and exception handling

Overview

Errors from the J.P. Morgan Wallet™ API broadly fall into two categories:

Wallet errors: Errors that Wallet sends directly, usually due to schema or business validations that Wallet performs.
External errors: Errors that payment processors or clearing systems send to Wallet due to issues downstream.

Because this is the Wallet documentation, here we only document Wallet errors. Wallet passes along external errors to you as-is—if you have questions about an external error that is not documented here, contact your J.P. Morgan representative.

You can find error codes for each endpoint on their respective API reference pages, in the 4xx and 5xx responses.

HTTP response status codes

When you send a request to a Wallet endpoint, the response contains an HTTP response status code.

The code indicates whether the request was successful:

200: The request was successful.
207: The request was partially successful, and/or there was a business validation error. Check the response for errors.
400, 401, 404, 500: The request was not successful and the response contains one or more errors.

Wallet returns different responses depending on the type of error and the HTTP response status code. The following are examples of the different types of responses.

Example: 207 - Account error

The following is an example of an error response that Wallet sends after receiving a request to create a virtual account.

Example: 207 - Account error

Json

{
    "errors": [
        {
            "errorCode": "FF02",
            "errorMsg": "Syntax Error: messageIdentification.virtualAccountDetails[0].virtualAccountIdentification - size must be between 0 and 35"
        }
    ]
}

Example: 207 - Transaction error - Batch level

The following is an example of an error response that Wallet sends after receiving a request to execute a transaction. This error occurred at the batch (group) level (originalGroupInformationAndStatus).

Example: 207 - Transaction error - Batch level

Json

{
    "originalGroupInformationAndStatus": {
        "statusReasonInformation": [
            {
                "reason": {
                    "code": "FF02",
                    "proprietary": "202"
                },
                "additionalInformation": [
                    "Syntax Error or Invalid Length : [messageIdentification]"
                ]
            }
        ]
    }
}

Example: 207 - Transaction error - Payment level

The following is an example of an error response that Wallet sends after receiving a request to execute a transaction. This error occurred at the payment level (originalPaymentInformationAndStatus).

Example: 207 - Transaction error - Payment level

Json

{
    "originalPaymentInformationAndStatus": {
        "statusReasonInformation": [
            {
                "reason": {
                    "code": "FF02",
                    "proprietary": "202"
                },
                "additionalInformation": [
                    "Syntax Error or Invalid Length : [paymentInformationId]"
                ]
            }
        ]
    }
}

Example: 207 - Transaction error - Transaction level

The following is an example of an error response that Wallet sends after receiving a request to execute a transaction. This error occurred at the transaction level (transactionInformationAndStatus).

Example: 207 - Transaction error - Transaction level

Json

{
    "originalPaymentInformationAndStatus": {
        "transactionInformationAndStatus": [
            {
                "statusReasonInformation": [
                    {
                        "reason": {
                            "code": "FF01",
                            "proprietary": "202"
                        },
                        "additionalInformation": [
                            "Invalid Length : paymentIdentification.endToEndIdentification"
                        ]
                    }
                ],
            }
        ]
    }
}

Example: 400 - Gateway error

The following is an example of an error response that Wallet sends after receiving a request that failed schema validation.

Example: 400 - Gateway error

Json

{
    "errors": [
        {
            "errorCode": "GE01",
            "errorMsg": "SchemaValidationFailure - $: unknown found, object expected"
        }
    ]
}

Example: 401 - Gateway error

The following is an example of an error response that Wallet sends after receiving a request that was improperly formatted.

Example: 401 - Gateway error

Json

{
    "originalGroupInformationAndStatus": {
        "statusReasonInformation": [
            {
                "reason": {
                    "code": "FF02",
                    "proprietary": "202"
                },
                "additionalInformation": [
                    "Syntax Error or Invalid Length : [messageIdentification]"
                ]
            }
        ]
    }
}

Example: 404 - Gateway error

The following is an example of an error response that Wallet sends after receiving a request with an incorrect program ID or endpoint.

Example: 404 - Gateway error

Json

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "No static resource ewallet/v2/payments/advanced-batch2153234565474568678.",
    "instance": "/ewallet/v2/payments/advanced-batch2153234565474568678"
}

Example: 500 - Gateway error

The following is an example of an error response that Wallet sends after encountering an unexpected server issue.

Example: 500 - Gateway error

Json

{
    "errors": [
        {
            "errorCode": "GE01",
            "errorMsg": "Generic Exception. "
        }
    ]
}

Wallet errors

Wallet errors are identified by codes that are returned in the response (usually errorCode or code).

Wallet error codes are formatted in the following way: <PREFIX><SEQUENCE>

<PREFIX>: Two- or three-character prefix that identifies the high-level business or technical category where the error occurred.
<SEQUENCE>: Number that corresponds to the specific detail of the failure within that category.

For example: AC01

Error prefixes

The following table lists the prefixes for Wallet error codes.

Wallet error prefixes
Prefix	Category	Description
AC	Account	Issues related to account status.
AG	Agent	Issues related to the financial institution or "agent."
AM	Amount	Problems with the currency or transaction value.
BE	Beneficiary	Missing or incorrect information about the creditor/debtor.
CH	Schema	Element is missing or incorrect.
DT	Date	Timing or date-related errors.
DU	Duplicate	The transaction or message ID is a duplicate.
EW	Wallet business validation	Business validation errors in Wallet.
FF	Format	Technical syntax or message format errors.
GCA	Gateway Error	Issues with authorization or other general API gateway errors.
GE	Generic Exception	Unspecified or general errors.
RC	Routing / BIC	Issues with bank identifiers or routing codes.
RR	Regulatory	Failure to comply with specific regulatory or tax requirements.

Error codes

The following tables list the error codes that Wallet can send in API responses.

Virtual accounts

The following table lists errors related to virtual accounts.

Wallet errors related to virtual accounts
Error code	Error message	Description
EW001	No data found for the criteria specified	Wallet did not find any transactions that match the parameters that you specified in the query. Change the parameters to be more broad.
EW002	Invalid Balance Type code	The `balanceType` query parameter in the request is invalid. Set it to one of the following values: `ITAV` `ITBD` `XPCD`
EW011	Threshold limit exceeded for creating accounts	You have created the maximum number of virtual accounts in your Wallet program. If you need to create more, contact your J.P. Morgan representative.
EW012	Parent account id is invalid	Confirm that the `messageIdentification.virtualAccountDetails.parentVirtualAccountIdentification` body parameter matches an open Virtual Summary Account (VSA) in your virtual account structure.
EW013	Parent account id field is mandatory for creating EVTA	If the `messageIdentification.virtualAccountDetails.virtualAccountType` body parameter is set to `EVTA`, confirm that you provide `virtualAccountDetails.parentVirtualAccountIdentification`.
EW014	Duplicate wallet account id	The `messageIdentification.virtualAccountDetails.virtualAccountIdentification` body parameter in the request is already assigned to a virtual account in your Wallet program. Set this parameter to a unique ID.
EW015	Incorrect Ewallet Account Type	Confirm that `messageIdentification.virtualAccountDetails.virtualAccountType` body parameter is set to either `EVTA` or `EVSA`.
EW017	Search returned more than the allowed maximum records	The query returned more than the maximum number of transactions (10,000). Make your criteria more narrow so that fewer than 10,000 transactions are returned.
EW029	MaximumBalance should be greater than MinimumBalance	Confirm that the `messageIdentification.virtualAccountDetails.accountOptions.balanceLimits.maximumBalance` body parameter is greater than `messageIdentification.virtualAccountDetails.accountOptions.balanceLimits.minimumBalance`.

Payments

The following table lists errors related to payments.

Wallet errors
Error code	Error message	Description
AC01	Account number invalid Virtual Account ID invalid	A bank account number or virtual account ID in the request is invalid. Confirm that the bank account numbers and virtual account IDs are correct.
AC02	Debtor Account number invalid or missing	The debtor account number in the request is invalid or missing. Confirm that the `paymentInformation.debtorAccount.identification.IBAN` or `paymentInformation.debtorAccount.identification.other.identification` body parameter is present and correct.
AC03	Creditor Account number invalid or missing	The creditor account number in the request is invalid or missing. Confirm that the `paymentInformation.creditTransferTransactionInformation.creditorAccount.identification.IBAN` or `paymentInformation.creditTransferTransactionInformation.creditorAccount.identification.other.identification` body parameter is correct.
AC04	Account Closed JPM Debtor Account Past Due Paper Creditor Account Past Due Paper Debtor proxy identifier type should be Transaction Creditor proxy identifier type should be Transaction Creditor proxy is not associated to EWallet structure account	There is an issue with an account in the transaction. See the error message for more details.
AC06	Account Blocked	An account in the request is blocked, prohibiting posting of transactions to it. Confirm that the accounts in the request are correct and can have transactions posted to them.
AC08	Branch code invalid or missing	The branch code of the debtor agent bank or creditor agent bank in the request is invalid or missing. Confirm that the branch codes are present and correct.
AC12	Account Type missing or invalid	The `paymentInformation.debtorAccount.type` or `paymentInformation.creditTransferTransactionInformation.creditorAccount.type` body parameter is missing or invalid. Confirm that both parameters are present and correct in the request.
AG01	Transaction not permitted	The transaction is forbidden for an account in the request. Contact your J.P. Morgan representative for support.
AG03	Transfer Type invalid or missing Type invalid or missing Transaction Type invalid	The transaction type in the request is invalid. Confirm that the `transactionType` header parameter is one of the following values and that the accounts support that transaction type: `PAYIN` `PAYINTO` `PAYINTOCOLLECTION` `PAYOUT` `PAYTO` `V2V`
AG08	Program ID is Invalid/Missing/Inactive Transaction failed due to invalid or missing entitlement	The program ID in the request is invalid or missing permissions. Confirm that the `programId` header parameter matches your Wallet program ID. If you still get this error, contact your J.P. Morgan representative for additional support.
AG09	Number of Transactions are not equal	The `groupHeader.numberOfTransactions` or `paymentInformation.numberOfTransactions` body parameter is not equal to the number of transactions in the request, which must be 1. Confirm that there is only one transaction in the request and set these parameters to 1.
AG10	Control Sum is not equal to total amounts of instruction	The `groupHeader.controlSum` or `paymentInformation.controlSum` body parameter is not equal to the total `paymentInformation.creditTransferTransactionInformation.amount` of all transactions in the request. There must only be 1 transaction in the request—confirm that its amount matches the control sum.
AG17	Batch level Control Sum does not equal total of Amounts in batch	The `paymentInformation.controlSum` body parameter is not equal to the total `paymentInformation.creditTransferTransactionInformation.amount` of all transactions in the request. There must only be 1 transaction in the request—confirm that its amount matches the control sum.
AG20	Batch level Number of Transactions does not equal total of instructions in batch	The `paymentInformation.numberOfTransactions` body parameter is not equal to the number of transactions in the request, which must be 1. Confirm that there is only one transaction in the request and set this parameter to 1.
AM10	Group level Control Sum does not equal total of Amounts in all batches Batch level Control Sum does not equal total of Amounts in batch Sum of instructed amounts does not equal the control sum Batch Control Sum does not equal total of Amounts in batch	The `groupHeader.controlSum` or `paymentInformation.controlSum` body parameter is not equal to the total `paymentInformation.creditTransferTransactionInformation.amount` of all transactions in the request. There must only be one transaction in the request—confirm that its amount matches the control sum.
AM11	Currency invalid or missing Currency values do not match	The currency is invalid for one of the transactions or accounts in the request, or the currency for an account and a transaction do not match. Confirm that the currency is present and correct for each transaction and account.
AM12	Amount is invalid or missing Invalid Amount	The `paymentInformation.creditTransferTransactionInformation.amount` body parameter is invalid or missing. Confirm that the parameter is present and correct for the transaction.
AM13	Transaction amount exceeds limits set by clearing system	The `paymentInformation.creditTransferTransactionInformation.amount` body parameter is greater than the maximum amount for the payment rail. Set the amount to a value less than the payment rail's maximum amount.
AM14	Instructed Amount exceeds available	The `paymentInformation.creditTransferTransactionInformation.amount` body parameter is greater than the maximum amount agreed between you and the bank. Set the amount to a value less than the maximum amount.
AM18	Invalid Number Of Transactions Number of transactions is invalid or missing	The `groupHeader.numberOfTransactions` or `paymentInformation.numberOfTransactions` body parameter is invalid or missing. Confirm that these parameters are present and match the number of transactions in the request, which must be 1.
AM19	Group level Number of Transactions does not equal total of instructions in all batches	The `groupHeader.numberOfTransactions` body parameter does not equal the number of transactions in the request. Change it to the correct value, which must be 1.
AM20	Batch Number of Transactions does not equal total of instructions in batch	The `paymentInformation.numberOfTransactions` body parameter does not equal the number of transactions in the request. Change it to the correct value, which must be 1.
BE01	Identification of end customer is not consistent with associated account number	The debtor or creditor account number is not associated with the provided name or other details.
BE18	Contact details missing or invalid	The `paymentInformation.debtor.contactDetails` or `paymentInformation.creditTransferTransactionInformation.creditor.contactDetails` body parameter is missing or invalid. Confirm that the parameters are present and correct.
BE20	Party name length invalid	The length of the `paymentInformation.debtor.name` or `paymentInformation.creditTransferTransactionInformation.creditor.name` parameter is greater than the maximum length for the payment rail. Set the value to a string with a length less than the maximum.
BE22	Debtor/Creditor Name is missing Missing Debtor Name Missing Creditor Name	The `paymentInformation.debtor.name` or `paymentInformation.creditTransferTransactionInformation.creditor.name` body parameter is missing. Add the missing parameters to the request.
DT01	Date invalid Invalid year format	One or more of the date parameters in the request is invalid. Check the API reference page for the endpoint and confirm that the date parameters that you provide adhere to the requirements.
DT02	Creation Date invalid	The `groupHeader.creationDateTime` body parameter is invalid. Confirm that the parameter is expressed in local time with the time zone offset from UTC in the following format: `YYYY-MM-DDThh:mm:ss±hh:mm`
DT04	Future date not supported	A date parameter in the request is in the future, which is not supported. Change the date to be either the current date or a date in the past.
DU01	Duplicate message Identification	The `groupHeader.messageIdentification` body parameter is not unique. Change the parameter to a unique ID that has not already been used for another message in your Wallet program.
DU02	Duplicate payment Information Identification	The `paymentInformation.paymentInformationIdentification` body parameter is not unique. Change the parameter to a unique ID that has not already been used for another payment batch in your Wallet program.
DU04	Duplicate endToEnd Identification Possible Duplicate Instruction	The `paymentInformation.creditTransferTransactionInformation.paymentIdentification.endToEndIdentification` body parameter is not unique. Change the parameter to a unique ID that has not already been used for another payment in your Wallet program.
FF01	Invalid Length Invalid File Format	One or more parameters in the request has an invalid length or file format. Check the API reference page for the endpoint and confirm that all parameters match the length and file format requirements.
FF02	Syntax Error Unable to determine debtor proxy account Unable to determine creditor proxy account Invalid Length Invalid Format Syntax error reason is provided as narrative information in the additional reason information	There is an issue with the formatting of a parameter in the transaction. See the error message for more details.
FF03	Invalid Scheme Proprietary Type Instruction type not supported for batch processing Multiple batches not supported in one instruction Too many instructions in batch	There is an issue with the formatting of a parameter in the transaction. See the error message for more details.
FF03_EW063	Too many instructions in one batch. Please limit to 500 or less.	Change the `paymentInformation.creditTransferTransactionInformation` body parameter to contain only one transaction object.
FF05	Local Instrument code is missing or invalid	The `paymentInformation.paymentTypeInformation.localInstrument` body parameter is missing or invalid. Confirm that the parameter is present and correct.
FF06	Category Purpose code is missing or invalid	The `paymentInformation.paymentTypeInformation.categoryPurpose` body parameter is missing or invalid. Confirm that the parameter is present and correct.
FF08	Client End-to-End ID is missing or invalid Invalid Transaction Code	The `paymentInformation.creditTransferTransactionInformation.paymentIdentification.endToEndIdentification` body parameter is missing or invalid. Confirm that the parameter is present and correct in the request.
FF10	Bank technical issue - Contact J.P. Morgan Client Service	There is a technical issue with client onboarding and implementation. Contact your J.P. Morgan representative for support.
NARR	Exchange Rate Type invalid or missing ChargeBearer invalid or missing PaymentMethod invalid or missing NamePrefix invalid or missing Service Level Code or Party invalid Address Type is invalid Clearing System Id Type invalid Misc. exception - Contact J.P. Morgan Client Service Unspecified error - Contact J.P. Morgan Client Service	There was an issue. See the error message for more details and contact your J.P. Morgan representative for support.
RC01	Bank identifier Incorrect	The debtor account number (`paymentInformation.debtorAccount.identification.other.identification`) or the creditor account number (`paymentInformation.creditTransferTransactionInformation.creditorAccount.identification.other.identification`) is incorrect. Confirm that the account numbers match the account numbers provided by each bank.
RC02	Bank identifier Incorrect	The debtor account number (`paymentInformation.debtorAccount.identification.other.identification`) or the creditor account number (`paymentInformation.creditTransferTransactionInformation.creditorAccount.identification.other.identification`) is incorrect. Confirm that the account numbers match the account numbers provided by each bank.
RC03	Debtor bank identifier invalid or missing	The debtor account number (`paymentInformation.debtorAccount.identification.other.identification`) is invalid or missing. Confirm that the parameter is present and correct in the request.
RC04	Instruction incorrect for specific service offered by the Debtor Agent Creditor bank identifier invalid or missing	There is an issue with the debtor agent (`paymentInformation.debtorAgent`) or the creditor agent (`paymentInformation.creditTransferTransactionInformation.creditorAgent`), or the creditor account number (`paymentInformation.creditTransferTransactionInformation.creditorAccount.identification.other.identification`). Confirm that the debtor and creditor account numbers are correct.
RC05	BIC invalid or missing	The debtor agent BIC (`paymentInformation.debtorAgent.financialInstitutionIdentification.bic`) or the creditor agent BIC (`paymentInformation.creditTransferTransactionInformation.creditorAgent.financialInstitutionIdentification.bic`) is invalid or missing. Confirm that the parameters are present and correct.
RC08	Clearing System Member identifier invalid or missing.	The debtor agent clearing system member ID (`paymentInformation.debtorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification`) or the creditor agent clearing system member ID (`paymentInformation.creditTransferTransactionInformation.creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification`) is invalid or missing. Confirm that the parameters are present and correct.
RC10	Clearing System Member identifier invalid or missing.	The debtor agent clearing system member ID (`paymentInformation.debtorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification`) or the creditor agent clearing system member ID (`paymentInformation.creditTransferTransactionInformation.creditorAgent.financialInstitutionIdentification.clearingSystemMemberIdentification`) is invalid or missing. Confirm that the parameters are present and correct.
RR02	Ultimate Debtor Name or Address missing	The `paymentInformation.creditTransferTransactionInformation.ultimateDebtor` body parameter is missing the name or address. Confirm that the parameters are present in the request.
RR04	Debtor Party information is not FATF Compliant Party information is not FATF Compliant Regulatory Reason - Contact J.P. Morgan Client Service	A parameter in the request is not compliant with one or more regulations. Contact your J.P. Morgan representative for more information.
RR07	Remittance information not allowed for payment type	The `paymentInformation.creditTransferTransactionInformation.remittanceInformation` body parameter is not allowed for this payment type. Remove the parameter from the request.

General errors

The following table lists general Wallet errors.

General Wallet errors
Error code	Category	Description
CH17	Element is not allowed	A parameter in the request is not allowed. Check the API reference page for the endpoint and confirm that the parameters you provide adhere to the requirements.
CH21	Mandatory element missing	A required parameter in the request is missing. Check the API reference page for the endpoint and confirm that you include all required parameters in the request.
CH22	Prohibited field is present	A parameter in the request is prohibited. Check the API reference page for the endpoint and remove the prohibited parameter.
CH23	Cannot be passed together Or Either one is mandatory	Two or more parameters in the request cannot both be present. Check the documentation for the payment rail and remove one of the parameters.
COUNTRY	Country code is invalid	A country code in the request is invalid. Confirm that all country codes are in the two-character ISO 3166 format.
CURR	Currency invalid or missing	A currency parameter is invalid or missing. Confirm that all currency parameters are present and are in the three-character ISO 4217 format.
GCA-001	Unauthorized Access	You do not have authorization to send this request. Contact your J.P. Morgan representative.
GCA-003	Unauthorized Access	You do not have authorization to send this request. Contact your J.P. Morgan representative.
GCA-030	API Processing Error	An unspecified error occurred. Try again later and/or contact your J.P. Morgan representative.
GCA-103	The programId not found	Wallet could not match the `programId` that you provided in the header to an existing Wallet program. Confirm that the `programId` is correct.
GE01	Generic Error	An unspecified error occurred. Try again later and/or contact your J.P. Morgan representative.

External errors

Wallet has many validations to try and ensure that requests are accepted downstream. However, Wallet is not able to validate everything, and sometimes even if a request is sent successfully from Wallet to a payment processor or clearing system, it might be rejected downstream due to some issue with the data in the request.

To give a request its best chance of succeeding downstream, follow the requirements outlined in the documentation. The same API endpoint might have different requirements depending on the clearing system or other factors, so follow the requirements for your specific scenario.

If you receive an external error from Wallet that is not documented here and you are not able to resolve it on your own, reach out to us by following the guidance in Support.

Support

For client test support, contact your technical implementation manager.

For production support, contact API service support: api.service.support@jpmorgan.com