Profile errors

Copy

Handle personal and business profile validation errors.

Profile operations validate identity, contact, address, and business information. Treat the current operation schema as the source of truth for required fields. Process every returned error and use path to associate it with an input.

Response excerpts show only the entries for the named code from a documented response. The complete response can contain additional errors.

On this page:

• Create a personal profile
• Create a business profile
• Send only one business category format
• Handle a profile conflict
• Build country-specific addresses
• Legacy personal profile errors
• Legacy address errors
• Handle profile error messages

See the 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.

Create a personal profile

Endpoint: POST /profiles/personal-profile

See the create a personal profile operation for the current request and response schema.

Use the current schema for required fields and process any returned validation items. The legacy identifiers listed later on this page are documented for different endpoints and should not be assumed to apply to this operation.

Create a business profile

Endpoint: POST /profiles/business-profile

See the create a business profile operation for the current request and response schema. The operation can return several field-specific api.* errors in one response.

{
  "errors": [
    {
      "code": "api.businessName.missing",
      "message": "Please specify the name of your business",
      "path": "businessName",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.registrationNumber.missing",
      "message": "Please specify the registration number of your business ",
      "path": "registrationNumber",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.industryCategories.invalid",
      "message": "Please provide at least one valid industry category",
      "path": "industryCategories",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.address.missing",
      "message": "Please specify the address of your business",
      "path": "address",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.companyType.missing",
      "message": "Please select a company type",
      "path": "companyType",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.businessName.invalid",
      "message": "Business name contains invalid characters",
      "path": "businessName",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.businessName.size.too.short",
      "message": "Business name must be at least 1 character long",
      "path": "businessName",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.companyType.invalid",
      "message": "Invalid company type selected",
      "path": "companyType",
      "arguments": null
    }
  ]
}

{
  "errors": [
    {
      "code": "api.industryCategories.forbidden",
      "message": "One or more supplied industry categories is not permitted",
      "path": "industryCategories",
      "arguments": null
    }
  ]
}

Validate owners and directors

• Validate every object in an owners or directors array.
• Provide the complete identity, role, contact, and address data required by the current schema.
• Process every returned error because different objects can fail for different reasons.
• Use the returned path to map the error to the correct person and field.

Send only one business category format

Endpoints: POST /profiles/business-profile, PUT /profiles/{profileId}/business-profile

industryCategories and the deprecated firstLevelCategory/secondLevelCategory pair are mutually exclusive. A request that supplies both is rejected with a 400 on the industryCategories path.

1. Send industryCategories and omit firstLevelCategory and secondLevelCategory from the request entirely.
2. Do not send the new field alongside the legacy pair to move an existing profile across. Drop the legacy fields in the same request.
3. Apply the same rule on update. A request that changes both formats at once is rejected.

No dedicated error code is documented for this rejection. Use the industryCategories path to identify it rather than the message text.

For the values accepted by each operation, see the Wise business categories list. To move an existing integration off the legacy pair, see Migrating to industry categories.

Handle a profile conflict

Profile creation can return 409 when a matching profile already exists, particularly when the original request did not use an idempotency identifier.

1. List the user's profiles before creating another one.
2. Reconcile whether the original request succeeded.
3. Reuse the same X-idempotence-uuid only when retrying the same logical creation attempt.

Do not treat the status alone as a reusable error code. Add a returned identifier to this catalogue only after its public meaning is confirmed.

Build country-specific addresses

Before creating or updating an address:

1. Call the get address requirements operation.
2. Render the returned fields and validation constraints.
3. Preserve field names exactly when mapping the form to the request.
4. Process every returned validation error.

Country requirements can change. Do not maintain a permanent client-side list as your only source of truth.

Legacy personal profile errors

Endpoint: POST /v1/profiles

These identifiers are documented for the legacy profile operation. Their applicability to POST /profiles/personal-profile is not established here.

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "message": "Missing details property",
      "arguments": []
    }
  ]
}

{
  "errors": [
    {
      "code": "MISSING",
      "message": "Please enter your first name",
      "path": "firstName",
      "arguments": [
        "firstName"
      ]
    },
    {
      "code": "MISSING",
      "message": "Property [lastName] cannot be blank",
      "path": "lastName",
      "arguments": [
        "lastName"
      ]
    }
  ]
}

{
  "errors": [
    {
      "code": "ERROR",
      "message": "Unparseable date",
      "path": "dateOfBirth",
      "arguments": [
        "dateOfBirth"
      ]
    }
  ]
}

{
  "errors": [
    {
      "code": "TOO_SMALL",
      "message": "Value provided is too short. Please enter a valid phone number",
      "path": "phoneNumber",
      "arguments": [
        "phoneNumber",
        "+123",
        "5",
        "25"
      ]
    }
  ]
}

{
  "errors": [
    {
      "code": "UNEXPECTED",
      "message": "Please enter a valid phone number",
      "path": "phoneNumber",
      "arguments": [
        "phoneNumber",
        "+123"
      ]
    }
  ]
}

Legacy address errors

Endpoint: POST /v1/addresses

The published legacy address guide documents UNEXPECTED_ERROR with HTTP 500 for missing request details or a required postcode. Correct these known request defects before resubmitting; do not assume every 500 is transient.

Wise encountered an unexpected validation or service failure.

What to do

• Confirm that the request matches the current operation schema.
• Log a redacted response signature for investigation.
• Do not display diagnostic text directly to the end user.

Retry conditions

Correct the missing details or required postcode before resubmitting. Reconcile an uncertain create result before repeating it.

Handle profile error messages

• Display returned messages only for user-correctable input.
• Map authentication, ownership, and service failures to safe messages.
• Do not parse message text or use it for programmatic branching.
• Redact identity, contact, address, and business data from logs.