---
title: "Wallet Errors"
source_url: https://docs.rapyd.net/en/wallet-errors.html
lang: en
---

# Wallet Errors

The following error codes and messages appear in REST responses when an error prevents completion of the request.

| Wallet Errors |
| --- |
| **Error code:** ERROR_CREATE_USER_EWALLET_REFERENCE_ID_ALREADY_EXISTS  **Message:** The request tried to create a wallet, but the reference ID was already in use. The request was rejected. Corrective action: For `ewallet_reference_id`, enter a unique string.  **Explanation:** The value for the reference ID must be unique. Use a value that has not been used before. |
| **Error code:** ERROR_CREATE_USER_INVALID_EWALLET_REFERENCE_ID  **Message:** The request tried to create a wallet, but the ewallet reference ID was not valid. The request was rejected. Corrective action: Set `ewallet_reference_id` to a string of less than 200 characters.  **Explanation:** The reference ID provided exceeds the maximum character limit or contains unsupported formats. Shorten the string to under 200 characters.  **Correct Example:**   ```json {     "ewallet_reference_id": "CMYK-2026-04-30a" } ``` |
| **Error code:** ERROR_CREATE_WALLET_CNLS_PARTNER_QUERY_REFERENCE_MISMATCH  **Message:** The request tried to create a wallet, but the `cnls_partner_query_reference` value does not match the value in the Rapyd Verify solution. The request was rejected. Corrective action: Review the value of the `cnls_partner_query_reference` and if necessary, modify it and rerun the request. If its value is correct then contact Rapyd support.  **Explanation:** The reference ID for the compliance check does not match the CNLS reference ID you created for this merchant. For `cnls_partner_query_reference`, use the value you assigned to `partner_query_reference` when you ran [Initiate Merchant Query](https://docs.rapyd.net/en/initiate-merchant-query.md "Initiate Merchant Query"). |
| **Error code:** ERROR_EWALLET_ALREADY_ASSIGNED_TO_THIS_CUSTOMER  **Message:** The request tried to assign a wallet to a customer, but the customer already had this wallet. The request was rejected. Corrective action: None. Determine why an effort was made to duplicate this assignment.  **Explanation:** You attempted to link a wallet to a customer object that is already linked. Check your internal logic to prevent redundant assignment calls. |
| **Error code:** ERROR_EWALLET_DISABLED  **Message:** The request attempted an operation that requires a wallet, but the wallet is disabled. The request was rejected. Corrective action: Enable the wallet.  **Explanation:** The target wallet is currently in a disabled state and cannot process transactions. Use the [Change Wallet Status](https://docs.rapyd.net/en/change-wallet-status.md "Change Wallet Status") endpoint to change the status to **active**.  **Correct Example:**   ```json post /v1/user/ewallet_df9de1b6310514f9c11a3f52dddd9ca4/statuses/enable" ``` |
| **Error code:** ERROR_EWALLET_DISABLED_BY_SUPPORT  **Message:** The request attempted to enable a wallet, but the wallet was disabled by Support. The request was rejected. Corrective action: Contact Support in order to enable this wallet.  **Explanation:** The wallet has been locked by Rapyd's support or compliance team. Contact Rapyd Client Support to resolve the underlying issue. |
| **Error code:** ERROR_FIRST_NAME_CONTAINS_ILLEGAL_CHARS  **Message:** The request attempted an operation that requires a person's first name, but the name contained special characters. The request was rejected. Corrective action: Use only alphabetic characters and spaces for `first_name`.  **Explanation:** The `first_name` field includes symbols or numbers that are not permitted. Remove any non-alphabetic characters from the string. |
| **Error code:** ERROR_GET_EWALLET  **Message:** The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the ID of a valid wallet, a string starting with **ewallet_**.  **Explanation:** The system could not locate a wallet matching the provided ID. Verify that the ID is correct and exists in your environment. |
| **Error code:** ERROR_GET_USER  **Message:** The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the ID of a valid wallet that has not been deleted. The ID is a string starting with **ewallet_**.  **Explanation:** The requested wallet ID does not exist or has been permanently deleted. Verify the wallet ID in your records before retrying. |
| **Error code:** ERROR_INVALID_EWALLET  **Message:** The request attempted an operation that requires a wallet, but the wallet was not recognized. The request was rejected. Corrective action: Use the ID of a valid wallet, a string starting with **ewallet_**.  **Explanation:** The provided wallet identifier is formatted incorrectly or does not exist. Ensure that the ID begins with the correct prefix and is active.  **Error Example:** `get /v1/ewallets/_b9cbf3f4691aab019efacc3e376548df`  **Correct Example:**   ``` get /v1/ewallets/ewallet_b9cbf3f4691aab019efacc3e376548df   ``` |
| **Error code:** ERROR_INVALID_EWALLET_REFERENCE_ID  **Message:** The request attempted an operation that requires the ewallet reference ID, but the ewallet ID was not valid. The request was rejected. Corrective action: Set `ewallet_reference_id` to a string of less than 200 characters.  **Explanation:** The reference ID provided for an update or retrieval is invalid. Ensure the `ewallet_reference_id` is a valid string that meets length requirements. |
| **Error code:** ERROR_INVALID_EWALLET_TYPE  **Message:** The request attempted an operation that requires the `type` parameter, but the type was not a recognized value. The request was rejected. Corrective action: Set `type` to one of the following values: **person**, **company**, **client**.  **Explanation:** An unsupported value was sent for the wallet category. Change the `type` to a supported value.  **Error Example:** `{"type":"individual"}`  **Correct Example:**   ```json {     "type": "person" } ``` |
| **Error code:** ERROR_INVALID_EWALLET_VERIFICATION_STATUS  **Message:** The request attempted an operation that requires the verification status, but the verification status was not valid. The request was rejected. Corrective action: Set `verification_status` to one of the following values: **verified**, **not verified**  **Explanation:** The value assigned to the verification status field is not recognized by the API. Use only supported values. |
| **Error code:** ERROR_NOT_PERSON_WALLET  **Message:** The request attempted an operation that requires a wallet with `type` = **person**, but the wallet was not of that type. The request was rejected. Corrective action: None. Use a wallet with `type` set to **person**.  **Explanation:** Certain actions, such as individual identity verification, are only available for wallets of type **person**. Use the ID of a personal wallet. |
| **Error code:** ERROR_PAYCODE_AND_REFUND_CODE_OBSOLETE  **Message:** The request attempted an operation that requires a pay code or refund code, but these codes are now obsolete. The request was rejected. Corrective action: Use [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") and related methods.  **Explanation:** You are using legacy parameters that are no longer supported. Update your integration to use the newer Create Payment workflows. |
| **Error code:** ERROR_UPDATE_EWALLET_TYPE  **Message:** The request tried to update a wallet type, but the `type` cannot be changed. The request was rejected. Corrective action: None. Create a new wallet.  **Explanation:** The `type` field cannot be changed once the wallet is created. Instead, you must create a new wallet with the correct type. |
| **Error code:** ERROR_UPDATE_FUNDS  **Message:** The request tried to add funds to or remove funds from a wallet, but the wallet was not found. The request was rejected. Corrective action: Use a valid wallet phone number in E.164 format, or a valid wallet ID, which is a string starting with **ewallet_**.  **Explanation:** The fund transfer failed because the target wallet could not be identified. Verify the wallet ID or the E.164 phone number. |
| **Error code:** ERROR_UPDATE_USER  **Message:** The request tried to update a wallet, but the wallet was not found. The request was rejected. Corrective action: Use a valid wallet phone number in E.164 format, or a valid wallet ID, which is a string starting with **ewallet_**.  **Explanation:** The system could not locate the wallet specified in the [Update Wallet](https://docs.rapyd.net/en/update-wallet.md "Update Wallet") request. Check that the ID is correct and the wallet hasn't been deleted. |
| **Error code:** ERROR_UPDATE_USER_EWALLET_REFERENCE_ID_ALREADY_EXISTS  **Message:** The request tried to update a wallet, but the reference ID was already in use. The request was rejected. Corrective action: For `ewallet_reference_id`, enter a unique string.  **Explanation:** You attempted to update a wallet's reference ID to a value that is already taken by another wallet. Provide a unique string value. |
| **Error code:** ERROR_WALLET_INSUFFICIENT_FUNDS  **Message:** The request tried to transfer funds from a Rapyd wallet, but the wallet did not have sufficient funds in the required currency. The request was rejected. Corrective action: Transfer funds to the wallet in the required currency and resubmit the request.  **Explanation:** The transaction amount exceeds the current available balance in the specified currency. Add the required currency to the wallet balance before retrying. |
| **Error code:** ERROR_WALLET_TYPE_NOT_PERSON  **Message:** The request attempted an operation that requires a person wallet, but the wallet was not of that type. The request was rejected. Corrective action: None. Set `ewallets.ewallet` to the ID of a Rapyd Wallet of type person.  **Explanation:** The chosen wallet is not a personal wallet, which is required for this specific API call. Switch to a wallet ID where the `type` is set to **person**. |
| **Error code:** EWALLET_BUSINESS_DETAILS_ADDRESS_LINE1_NOT_VALID  **Message:** The request created a company wallet, but the first line of the business address was not found. The wallet was created with no `business_details` object, and it is not valid without it. Corrective action: Use [Update Wallet](https://docs.rapyd.net/en/update-wallet.md "Update Wallet") to set `line1` in the `address` object to a string made up of alphabetic characters and spaces.  **Explanation:** The required street address line is missing or invalid for a company wallet. Update the wallet with a valid string for `line1`. |
| **Error code:** EWALLET_BUSINESS_DETAILS_ADDRESS_NAME_NOT_VALID  **Message:** The request created a company wallet, but the name associated with the business address was not found or contained special characters. The wallet was created with no `business_details` object, and it is not valid without it. Corrective action: Use [Update Wallet](https://docs.rapyd.net/en/update-wallet.md "Update Wallet") to set `name` in the `address` object to a string made up of alphabetic characters and spaces.  **Explanation:** The business name in the address object is missing or contains illegal characters. Update the wallet with a clean alphabetic string for the `name` field. |
| **Error code:** EWALLET_UPDATED_WITH_NO_BUSINESS_DETAILS_DUE_TO_INVALID_ADDRESS  **Message:** The request tried to update a wallet, but the business address was missing required information or contained special characters. The request was rejected. Corrective action: Inside the `address` object, which is inside the `business_details` object, provide `name` with alphanumerics and spaces and `line_1` with a string.  **Explanation:** The update failed because fields in `business_details.address` were malformed. Correct the values for the `name` and `line_1` fields and resubmit. |
| **Error code:** EWALLET_WITH_ACCOUNT_CANNOT_BE_DELETED  **Message:** The request tried to delete a wallet, but the wallet held an account. The request was rejected. Corrective action: None. Determine why an attempt was made to delete the wallet.  **Explanation:** Wallets with accounts cannot be deleted even if all balances are 0. You can disable the wallet with [Change Wallet Status](https://docs.rapyd.net/en/change-wallet-status.md "Change Wallet Status"). |
| **Error code:** EWALLET_WITH_VIRTUAL_ACCOUNT_CANNOT_BE_DELETED  **Message:** The request tried to delete a wallet, but the wallet held a virtual account. The request was rejected. Corrective action: Close all of the wallet’s virtual accounts and try again.  **Explanation:** A wallet cannot be deleted while it still has active virtual accounts (vIBANs). Close the virtual accounts first. |
| **Error code:** INVALID_ACCOUNT_CURRENCY  **Message:** Please contact Rapyd Client Support.  **Explanation:** The request tried to set a limit on an account in a wallet, but the relevant currency account could not be identified. Verify that you specified the right currency of the account. |
| **Error code:** INVALID_ACCOUNT_LIMIT_TYPE  **Message:** The request attempted an operation on a wallet account, but the balance type was not recognized or the account was not found. The request was rejected. Corrective action: Make sure the wallet has the indicated account, and set `type` to **max_balance_limit** or **min_balance_threshold**.  **Explanation:** The request tried to set a limit on an account in a wallet, but the operation failed. Verify that you specified the right currency of the account and that `type` is set to **max_balance_limit** or **min_balance_threshold**. |
| **Error code:** INVALID_EMAIL  **Message:** The request attempted an operation that requires an email address, but the email was not valid or is already in use. The request was rejected. Corrective action: Provide a valid, unique email address for `email`.  **Explanation:** The email provided is either malformed or already registered to another user. Provide a unique, correctly formatted email address.  **Error Example:** `{"email":"john.doe.at.rapyd.net"}`  **Correct Example:**   ```json {     "email": "user_123456789@rapyd.net" } ``` |
| **Error code:** INVALID_EWALLET_ACCOUNT_ID  **Message:** The request tried to set or delete a limit on a wallet account, but the account was not found. The request was rejected. Corrective action: Add funds to the wallet in the currency you want, then set `account_id` to the correct account ID, or set `currency` to the currency of the account.  **Explanation:** The specific currency account in the wallet could not be identified. Verify the `account_id` or use the correct currency code for the account. |
| **Error code:** INVALID_EWALLET_TYPE  **Message:** The request tried to create a wallet, but the wallet type could not be determined. The request was rejected. Corrective action: Set `type` to **person** or **company**.  **Explanation:** The wallet creation request is missing the required `type` field. For a user wallet, define `type` as **person** or **company**. For a client wallet, contact Rapyd Client Support. |
| **Error code:** INVALID_LAST_NAME  **Message:** The request tried to perform an operation that requires the family name of an individual, but the `last_name` field was blank or invalid. The request was rejected. Corrective action: Submit a valid last name.  **Explanation:** The `last_name` field is empty or contains illegal characters. Provide the user's family name using alphabetic characters and spaces only. |
| **Error code:** LENGTH_OF_STATEMENT_DESCRIPTOR_EXCEEDS_MAXIMUM  **Message:** The request attempted an operation that uses a statement descriptor, but its length exceeds the maximum allowed length. The request was rejected. Corrective action: For the 'statement_descriptor' body parameter, enter a string of 1-22 alphanumeric characters and spaces. |
| **Error code:** MISSING_EWALLET_CONTACT_TYPE  **Message:** The request tried to create or update a wallet contact, but the contact type was missing. The request was rejected. Corrective action: Set `type` to one of the following values: **personal**, **business**.  **Explanation:** The contact type must be set to **personal** or **business**. |
| **Error code:** MISSING_EWALLET_ID  **Message:** The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the ID of a valid wallet.  **Explanation:** The wallet identifier is incorrect or missing from the request body or URL path. Provide the correct wallet ID. |
| **Error code:** MISSING_EWALLET_TOKEN  **Message:** The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Provide a valid wallet ID.  **Explanation:** The wallet identifier is incorrect or missing from the request body or URL path. Provide the correct wallet ID. |
| **Error code:** MISSING_PHONE_NUMBER_OR_EWALLET_ID  **Message:** The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Provide the wallet's phone number in E.164 format or wallet ID, which is a string starting with **ewallet_**.  **Explanation:** The API requires at least one method to identify the wallet (either ID or phone). |
| **Error code:** USER_ALREADY_EXISTS  **Message:** The request tried to assign a phone number to a wallet, but the phone number is already in the database. A wallet must have a unique phone number, but wallet contacts are not restricted. The request was rejected. Corrective action: In the `contact` object, assign the number to the `phone_number` field.  **Explanation:** The phone number is already registered to another wallet. Use [Update Wallet Contact](https://docs.rapyd.net/en/update-wallet-contact.md "Update Wallet Contact") and assign the number to `phone_number`.  **Correct Example:**   ```json post v1/ewallets/ewallet_b355f1e8657f2a02ae38d060c9512dd6/contacts/cont_964aa848bf107c2ebe819fd8ce1a85a3 {     "phone_number": "+12125551234" } ``` |