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

# Beneficiary Errors

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

> **Note:**
>
> See also [Card Network Errors](https://docs.rapyd.net/en/card-network-errors.md "Card Network Errors").

| Beneficiary Errors |
| --- |
| **Error code:** ERROR_BENEFICIARY_DETAILS_IN_REQUEST_AND_SAVED_BENEFICIARY_DETAILS_MISMATCH  **Message:** The request attempted an operation that requires a `beneficiary` ID, but the details in the request do not match the details in the saved beneficiary object. The request was rejected. Corrective action: Use the values that were saved in the beneficiary object or create a new beneficiary.  **Explanation:** You provided a `beneficiary` ID together with explicit details that conflict with the original saved data. Match the request body to the saved entity or omit the redundant fields. |
| **Error code:** ERROR_CREATE_BENEFICIARY  **Message:** The request tried to create a beneficiary for a payout, but the country was not recognized. The request was rejected. Corrective action: In the `country` field, use the correct 2-letter ISO 3166-1 ALPHA-2 code.  **Explanation:** The `country` provided in the beneficiary details does not exist in the system. Use a valid code such as **SG** or **US**.  **Error Example:** `post /v1/payouts/beneficiary {"country":"UK"}`  **Correct Example:**   ```json post /v1/payouts/beneficiary {     "country": "GB",     "entity_type": "individual" } ``` |
| **Error code:** ERROR_CREATE_BENEFICIARY_COUNTRY_NOT_VALID  **Message:** The request tried to create a beneficiary for a payout, but the `country` was not recognized. The request was rejected. Corrective action: Use the correct 2-letter ISO 3166-1 ALPHA-2 code, in uppercase letters, for the `country` field.  **Explanation:** The value for `country` is missing or incorrect. Ensure that you provide a valid 2-letter identifier.  **Error Example:** `{"country":"UK"}`  **Correct Example:**   ```json {     "country": "GB" } ``` |
| **Error code:** ERROR_CREATE_BENEFICIARY_CURRENCY_NOT_VALID  **Message:** The request tried to create a beneficiary for a payout, but the `currency` was missing or not recognized. The request was rejected. Corrective action: Use the correct 3-letter ISO 4217 code for the currency, in uppercase letters, for the `currency` field.  **Explanation:** You failed to provide a valid 3-letter currency identifier. Check the response to [List Payout Method Types](https://docs.rapyd.net/en/list-payout-method-types.md "List Payout Method Types") to see which currencies are supported for the target country.  **Error Example:** `{"currency":"$"}`  **Correct Example:**   ```json {     "currency": "USD" } ``` |
| **Error code:** ERROR_DELETE_PAYOUT_BENEFICIARY  **Message:** The request tried to delete a beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary.  **Explanation:** You attempted to remove a beneficiary that does not exist or has already been deleted. Before you send the request, run [Retrieve Beneficiary](https://docs.rapyd.net/en/retrieve-beneficiary.md "Retrieve Beneficiary") to verify the ID.  **Correct Example:**   ```json delete /v1/payouts/beneficiary/beneficiary_94956e29ed5959a51afc6717787c00af ``` |
| **Error code:** ERROR_GET_BENEFICIARY  **Message:** The request attempted an operation that requires a payout beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary.  **Explanation:** You provided an invalid beneficiary ID in the path or body of the request. Ensure that the beneficiary exists by initially running the [Retrieve Beneficiary](https://docs.rapyd.net/en/retrieve-beneficiary.md "Retrieve Beneficiary") request.  **Error Example:** `get /v1/payouts/beneficiary/beneficiary_7723`  **Correct Example:**   ```json get /v1/payouts/beneficiary/beneficiary_cb009f46c8dcd85004c8054541287723 ``` |
| **Error code:** ERROR_UPDATE_BENEFICIARY_WITH_NO_NEW_FIELDS  **Message:** The request attempted to update a beneficiary field, but its value has already been defined. The request was rejected. Corrective action: Update only values of beneficiary fields that were not previously defined.  **Explanation:** You tried to modify a protected beneficiary field that cannot be changed after creation. |
| **Error code:** ERROR_VALIDATE_PAYOUT_BENEFICIARY  **Message:** The request tried to validate a beneficiary, but there was an error in the input fields. The request was rejected. Corrective action: Run [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields").  **Explanation:** The validation check failed due to invalid data in the beneficiary object. Ensure that all fields are valid according to the response in [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields"). |