{"templateId":"../../../@theme/Templates/Wide.tsx","sharedDataIds":{"sidebar":"sidebar-guides/developer/errors/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-header","error-code-heading","section","panel-left","panel-right"]},"type":"markdown"},"seo":{"title":"User errors","siteUrl":"https://docs.wise.com","projectTitle":"Wise Platform","description":"Handle validation and duplicate-user errors when creating Wise users.","keywords":["user errors","user creation","registration code","duplicate user"]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"user-errors","__idx":0},"children":["User errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"class":"sub-header"},"children":["Handle user creation and registration code errors."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["User creation errors identify invalid registration details or an email that already belongs to a Wise user. Process every item in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array and use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," to associate the error with an input."]},{"$$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":"#create-a-user"},"children":["Create a user"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#prevent-user-creation-errors"},"children":["Prevent user creation errors"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#handle-user-error-messages"},"children":["Handle user error messages"]}]}]},{"$$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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-user","__idx":1},"children":["Create a user"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /user/signup/registration_code"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The examples below are documented for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/user/signup/registration_code"]},". Match your API version when using them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/user/usercreate"},"children":["create a user operation"]}," for the current request and response schema."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"NOT_UNIQUE"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A value that must be unique is already in use. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," to identify the affected field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP status:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$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":["Check the field identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," before choosing a recovery action."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the email belongs to an existing Wise user, stop user creation and follow the account-linking or OAuth flow for your integration. Do not change the email to bypass that conflict."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not retry the same request."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response (v1)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"NOT_UNIQUE\",\n      \"message\": \"You're already a member. Please login\",\n      \"path\": \"email\",\n      \"arguments\": [\n        \"email\",\n        \"ma********************@wise.com\"\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"NotNull"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A required field is missing or has a null value. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," to identify each affected field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP status:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$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":["Provide all fields required by the current operation schema."]},{"$$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 adding the missing fields."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response (v1)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"NotNull\",\n      \"message\": \"must not be null\",\n      \"path\": \"email\",\n      \"arguments\": []\n    },\n    {\n      \"code\": \"NotNull\",\n      \"message\": \"must not be null\",\n      \"path\": \"registrationCode\",\n      \"arguments\": []\n    }\n  ]\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"Size"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A field does not meet its size restrictions: its length is below the allowed minimum or above the allowed maximum. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," to identify the field and check its applicable constraints."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP status:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$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 identify the field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate its length against the current operation schema and any limits supplied in the response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arguments"]}," as error-specific context."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after correcting the field length."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response (v1)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"Size\",\n      \"message\": \"size must be between 32 and 2147483647\",\n      \"path\": \"registrationCode\",\n      \"arguments\": [\n        \"2147483647\",\n        \"32\"\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"ERROR"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A field failed validation but the response uses a generic identifier. The endpoint and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]}," provide the specific meaning."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP status:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$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":["Associate the error with the field identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use a suitable returned message for user-correctable input, with a safe fallback."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not map ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}," to one universal meaning."]}]},{"$$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 field."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response (v1)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"ERROR\",\n      \"message\": \"Please provide a valid email\",\n      \"path\": \"email\",\n      \"arguments\": [\n        \"email\",\n        \"ma********************@w\"\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prevent-user-creation-errors","__idx":2},"children":["Prevent user creation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before creating a user:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide a valid email address."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate and store a unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registrationCode"]}," with at least 32 characters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Protect the registration code as you would other credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep it because the registration-code grant uses it to obtain tokens."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not depend on a particular code for every malformed request. Validate against the operation schema and use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["path"]},", where present, to locate the affected field."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-user-error-messages","__idx":3},"children":["Handle user error messages"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display a returned message only when it clearly describes user-correctable input."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not parse message text or use it for programmatic branching."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep email addresses and registration codes out of logs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Record the endpoint, HTTP status, code, and path for unknown errors."]}]}]},"headings":[{"value":"User errors","id":"user-errors","depth":1},{"value":"Create a user","id":"create-a-user","depth":2},{"value":"Prevent user creation errors","id":"prevent-user-creation-errors","depth":2},{"value":"Handle user error messages","id":"handle-user-error-messages","depth":2}],"frontmatter":{"template":"../../../@theme/Templates/Wide.tsx","seo":{"title":"User errors","description":"Handle validation and duplicate-user errors when creating Wise users.","keywords":["user errors","user creation","registration code","duplicate user"]},"markdown":{"toc":{"hide":true}}},"lastModified":"2026-09-22T05:59:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/developer/errors/users","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}