{"templateId":"../../../@theme/Templates/Wide.tsx","sharedDataIds":{"sidebar":"sidebar-guides/developer/errors/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-header","admonition","error-code-heading","section","panel-left","panel-right"]},"type":"markdown"},"seo":{"title":"Recipient errors","siteUrl":"https://docs.wise.com","projectTitle":"Wise Platform","description":"Handle Wise recipient validation, bank detail, address, and access errors.","keywords":["recipient errors","bank details","recipient validation","NOT_VALID"]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"recipient-errors","__idx":0},"children":["Recipient errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"class":"sub-header"},"children":["Handle recipient identity, bank, address, and access errors."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recipient requirements vary by currency, country, recipient type, and payment route. Retrieve the current requirements before creating a recipient, then handle every validation error returned by ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/recipient/recipientcreate"},"children":["create a recipient account"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recipient validation commonly uses a generic ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_VALID"]},". In these responses, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," is the most useful field for associating the error with your form."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Validation status"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recipient validation failures can use different ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," statuses across operations and service paths. Handle the documented response body instead of assuming all recipient validation uses only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," or only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On this page:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#recipient-error-format"},"children":["Recipient error format"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-recipient"},"children":["Create a recipient"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#notvalid-field-path-catalogue"},"children":["NOT_VALID field path catalogue"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#handle-multiple-field-errors"},"children":["Handle multiple field errors"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#use-dynamic-recipient-requirements"},"children":["Use dynamic recipient requirements"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#display-recipient-messages"},"children":["Display recipient messages"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#retry-recipient-requests"},"children":["Retry recipient requests"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/errors#choose-a-recovery-action"},"children":["shared handling guidance"]}," for choosing an action, displaying messages, and retrying safely. Ask the customer to correct details only when they can edit them. If your integration supplies or changes those values, correct its validation or mapping instead."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recipient-error-format","__idx":1},"children":["Recipient error format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A recipient response can contain several field errors in an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#NOT_VALID"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_VALID"]}," example"]}," for a verified response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the fields as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," to identify the affected form field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," within the recipient operation, not as a globally unique identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," as display text only when the error is user-correctable and the text suits your interface."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arguments"]}," as error-specific context. Do not assume that every response uses the same argument positions."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-recipient","__idx":2},"children":["Create a recipient"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /accounts"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/recipient/recipientcreate"},"children":["create a recipient operation"]}," for the current request and response schema. The codes below can apply when Wise validates or creates the recipient."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"NOT_VALID"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A recipient field is missing or invalid for the selected recipient type or payment route."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," to map the error to the affected input."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the current recipient requirements to correct the field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Process every item in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after correcting the identified fields."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"timestamp\": \"2026-08-18T10:15:30Z\",\n  \"errors\": [\n    {\n      \"code\": \"NOT_VALID\",\n      \"message\": \"Please specify an IBAN.\",\n      \"path\": \"IBAN\",\n      \"arguments\": [\"IBAN\"]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"MISSING"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A required recipient, identity, bank, or address field is absent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve the current recipient requirements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request the missing value and verify the request mapping."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after adding the required field."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"DATE_OF_BIRTH_REQUIRED"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The route requires the recipient's date of birth or the supplied date is invalid."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request a complete valid date in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," format."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preserve the recipient's full legal name when updating the recipient data."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after correcting the date of birth."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"ACCESS_DENIED"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The recipient is not available to the authenticated profile."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the profile, environment, token, and recipient ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show a generic unavailable-recipient message."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after correcting the access context."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"RECIPIENT_MISSING"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The referenced recipient is not available in the profile's recipient list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve the profile's recipients and reconcile the identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the required recipient if it does not exist."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after selecting or creating the correct recipient."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"RECIPIENT_CREATE_ERROR"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wise could not create the recipient because of an unexpected service condition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not ask the end user to change valid input without evidence."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile whether the recipient was created before sending another create request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Record the status, code, path, and trace identifier."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not automatically retry an unexplained failure. If a transient cause is confirmed, use bounded backoff only when duplicate creation is prevented or the original outcome has been reconciled."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"UNEXPECTED"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recipient validation or creation failed without a more specific public identifier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use a generic end-user message and do not display technical details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Record the HTTP status, code, path, operation, and trace identifier."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not automatically retry the unchanged request without a confirmed recovery path. Establish the cause and replay safety first."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"not_valid-field-path-catalogue","__idx":3},"children":["NOT_VALID field path catalogue"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_VALID"]}," is a generic recipient validation code. Its meaning comes from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]},", the recipient type, and the selected currency route. The same path can have several constraints, so do not map ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_VALID"]}," to one universal message."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Path"},"children":["Path"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Handling"},"children":["Handling"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountHolderName"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The recipient or account-holder name is missing, too short, or contains characters unsupported by the route."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request the recipient's full legal name. Follow the character and name-structure rules returned by recipient requirements."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legalEntityType"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legalType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The selected personal or business recipient type is missing or not supported for the account type."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Preserve the intended recipient type, refresh requirements, and submit an allowed value."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dateOfBirth"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date of birth is required, malformed, in the future, or outside the accepted age range."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request a complete date in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]}," format and validate calendar and range constraints before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The email is missing or malformed for a recipient type that requires it."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request a valid email address. Do not substitute an email-recipient flow unless the requirements make that type available."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The account identifier is missing, has an invalid length or format, or is incompatible with the selected bank or recipient type."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apply the current route constraints and ask for corrected details. Do not infer that a structurally valid number belongs to an account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The account type is missing or is not one of the values supported by the route."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Render the options supplied by requirements and submit the selected value unchanged."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IBAN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The IBAN is missing, malformed, or uses a country code that is incompatible with the route."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask for the complete IBAN and validate its basic structure before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sortCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The GBP bank sort code is missing, malformed, or unknown."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask for a supported sort code and keep it associated with the submitted account number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bsbCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Australian BSB is missing, not 6 digits, or unknown."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask for the 6-digit BSB and validate the format before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["abartn"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The US routing number is missing, malformed, unknown, or not supported for the selected payment rail."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask for a valid routing number. If the response identifies an ACH or wire incompatibility, select a compatible recipient type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ifscCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Indian Financial System Code (IFSC) is missing or malformed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask for a valid IFSC and preserve leading characters or zeroes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A route-specific bank code is missing, malformed, unknown, or unsupported."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the bank list or autocomplete data supplied for the route instead of maintaining a permanent local list."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["branchCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A route-specific branch is missing, malformed, or unsupported."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask the user to select or enter a supported branch using the format returned by requirements."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.country"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The country is missing or is not a supported ISO country code for the field."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submit the ISO format required by the operation and refresh dependent address requirements."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.city"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The recipient city is required but missing or invalid."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request a valid city and preserve the complete nested address object."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.firstLine"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The first address line is missing or exceeds the supported length."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request the street address and enforce the current maximum length before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.postCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The postal code is missing, malformed, or too long for the selected country."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apply the country-specific requirement and request a corrected postal code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The state or region is required or invalid for the selected country."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Render the state field when required and submit a supported state value or code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No usable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request failed a recipient-level rule rather than one field rule, or the response did not expose the target field."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Place the error in a form-level summary. Use a suitable returned message or a safe generic fallback and record the complete signature for investigation."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are common observed paths, not a replacement for the recipient requirements response. New fields and constraints can be introduced for additional routes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-multiple-field-errors","__idx":4},"children":["Handle multiple field errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not stop after the first item in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]},"."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Iterate over the complete ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Normalise each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," to your form's field identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Group errors that target the same field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display suitable field-level feedback."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Place errors with no usable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," in a form-level summary."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log unknown combinations of status, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," for review."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-dynamic-recipient-requirements","__idx":5},"children":["Use dynamic recipient requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prevent avoidable validation errors by using the requirements operations:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/recipient/recipientaccountrequirementsget"},"children":["Retrieve recipient account requirements"]}," for the selected currency and recipient type."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Render the returned fields and validation constraints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Refresh the requirements when a field indicates that a selection can change the remaining form."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate the current form using the available requirements operation before creating the recipient."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preserve values that remain applicable after a requirements refresh."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not maintain a static list of required bank fields for every currency corridor. Requirements can vary by route and recipient type."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"display-recipient-messages","__idx":6},"children":["Display recipient messages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recipient validation messages are often suitable for field-level feedback, but not every recipient error is safe to pass through."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display messages for clearly identified, user-correctable fields after checking that the wording suits your interface."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Map access, ownership, unexpected, and service errors to your own safe messages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not parse a message to determine the field or validation rule."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not expose rejected bank details in logs or monitoring labels."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retry-recipient-requests","__idx":7},"children":["Retry recipient requests"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_VALID"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING"]}," responses until the input changes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCESS_DENIED"]}," until you correct the profile or recipient context."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retry transient service failures with backoff only when duplicate creation is prevented or can be reconciled."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After a timeout, check whether the recipient was created before sending another create request."]}]}]},"headings":[{"value":"Recipient errors","id":"recipient-errors","depth":1},{"value":"Recipient error format","id":"recipient-error-format","depth":2},{"value":"Create a recipient","id":"create-a-recipient","depth":2},{"value":"NOT_VALID field path catalogue","id":"not_valid-field-path-catalogue","depth":2},{"value":"Handle multiple field errors","id":"handle-multiple-field-errors","depth":2},{"value":"Use dynamic recipient requirements","id":"use-dynamic-recipient-requirements","depth":2},{"value":"Display recipient messages","id":"display-recipient-messages","depth":2},{"value":"Retry recipient requests","id":"retry-recipient-requests","depth":2}],"frontmatter":{"template":"../../../@theme/Templates/Wide.tsx","seo":{"title":"Recipient errors","description":"Handle Wise recipient validation, bank detail, address, and access errors.","keywords":["recipient errors","bank details","recipient validation","NOT_VALID"]},"markdown":{"toc":{"hide":true}}},"lastModified":"2026-09-22T05:59:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/developer/errors/recipients","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}