Bulk user operations return detailed validation and processing errors to help you identify and resolve issues.

Error response structure

Error responses follow this structure. The following example shows an ambiguous group reference, where multiple groups share the same name:

{
  "reason": "REASON_GROUP_REFERENCE_AMBIGUOUS",
  "field_hint": "FIELD_GROUPS",
  "value_hint": "Marketing Team",
  "message": "Group reference is ambiguous, please use a unique identifier",
  "level": "LEVEL_ERROR",
  "value_reference": {
    "id": "",
    "name": "Marketing Team",
    "valid": false
  },
  "details": {
    "ambiguous_reference": {
      "possible_references": [
        {
          "id": "87b859dc-e616-40a3-939a-08c20969b105",
          "name": "Marketing Team"
        },
        {
          "id": "92c759dc-f716-41b3-849a-09d30969c205",
          "name": "Marketing Team"
        }
      ]
    }
  }
}

Error response fields

Each error response includes the following fields:

Field	Description
`reason`	The specific error code identifying the error type.
`field_hint`	The field where the error occurred.
`value_hint`	The value that caused the error.
`message`	A human-readable description of the error.
`level`	The severity of the error (`INFO`, `WARNING`, `ERROR`, or `FATAL`).
`value_reference`	Context about the value that caused the error.
`details`	Additional structured data to help resolve the error, such as possible valid options.

Error levels

Errors can have the following severity levels:

Level	Description
`INFO`	Provides context about the operation. Informational only and does not impact processing.
`WARNING`	Potential issue that may lead to unexpected results, but does not block processing.
`ERROR`	Prevents the field from being processed for this user.
`FATAL`	Critical problem that stops the user from being created or updated.

Error reasons

You might encounter the following error reasons during bulk user operations:

Reason	Description
`REASON_USER_EXISTS`	A user with this username already exists in the organization.
`REASON_USER_NOT_FOUND`	The user ID does not match any existing user in the organization.
`REASON_DUPLICATE_ROW`	Duplicate user entries were detected in the request.
`REASON_DUPLICATE_USERNAME`	The username appears more than once in the request or already exists in the organization.
`REASON_MUST_HAVE_ID_OR_USERNAME`	Each user record must include either a user ID or username.
`REASON_INVALID_ID_FORMAT`	The user ID is not in a valid format.
`REASON_INVALID_USERNAME_FORMAT`	The username must be a valid email address.
`REASON_ID_USERNAME_MISMATCH`	The provided username does not match the existing username for this user ID. Username updates are not currently supported.
`REASON_FIELD_MANDATORY_FOR_CREATION`	A required field is missing for creating a new user.
`REASON_CANNOT_CREATE_DEACTIVATED_USERS`	Users must be created as `active`. Creating a deactivated user is not allowed.
`REASON_FIELD_CHANGE_NOT_ALLOWED_FOR_CALLER`	You don't have permission to change the field for this action type.
`REASON_INVALID_SEAT_PERMISSION_SET_COMBINATION`	The permission set and seat type combination is not valid. Some permission sets can only be assigned to specific seat types.
`REASON_INVALID_VALUE_PASSWORD_TOO_WEAK`	The password does not meet the required strength criteria.
`REASON_INVALID_VALUE_PASSWORD_CANNOT_UPDATE_USERS_PASSWORD`	Passwords for existing users cannot be updated through this API.
`REASON_INVALID_VALUE_REFERENCE_NAME_DOES_NOT_FOUND`	The referenced site, group, or attribute name could not be found.
`REASON_INVALID_VALUE_REFERENCE_ID_DOES_NOT_FOUND`	The referenced site, group, or attribute ID could not be found.
`REASON_PERMISSION_SET_PERMISSION_DENIED`	You don't have permission to modify other users' permission sets.
`REASON_PERMISSION_SET_USER_NOT_ACTIVE`	Permission sets cannot be modified for inactive users. Activate the user first.
`REASON_PERMISSION_SET_NOT_FOUND`	The specified permission set was not found in the organization.
`REASON_INVALID_PERMISSION_SET_FOR_ORGANIZATION_TIER`	The permission set cannot be used with your organization's current plan. For example, custom permission sets are only available on Premium Plan or Enterprise Plan.
`REASON_USER_ATTRIBUTE_DUPLICATE_ATTRIBUTE`	The same user attribute was specified multiple times for this user in the request.
`REASON_USER_ATTRIBUTE_NOT_FOUND`	The user attribute could not be found in the organization.
`REASON_USER_ATTRIBUTE_INVALID_ATTRIBUTE_TYPE`	The attribute type is not supported. This may occur if a new attribute type is added before it's supported by the endpoint.
`REASON_USER_ATTRIBUTE_INVALID_SELECT_VALUE`	The provided value is not one of the allowed options for this select-type attribute.
`REASON_USER_ATTRIBUTE_INVALID_USER_ID_VALUE`	The value is not a valid user ID.
`REASON_USER_ATTRIBUTE_INVALID_TIMESTAMP_VALUE`	The value is not a valid timestamp.
`REASON_USER_ATTRIBUTE_INVALID_STRING_VALUE`	The string value is not valid. For example, some fields do not allow empty strings.
`REASON_INVALID_SEAT_TYPE_FOR_ORGANIZATION_TIER`	The seat type is not supported on your organization's current plan. For example, lite seats aren't available on the Free Plan.
`REASON_SEAT_LIMIT_REACHED`	The request would exceed your organization's seat limit.
`REASON_GROUP_NOT_FOUND`	The group could not be found in the organization.
`REASON_GROUP_DUPLICATE_ENTRY`	The same group was listed more than once for this user.
`REASON_GROUP_CANNOT_ASSIGN_TO_DEACTIVATED_USER`	Groups cannot be assigned to users who are deactivated or will be deactivated.
`REASON_GROUP_INVALID_REMOVE_REFERENCE`	The group reference specified for removal is invalid.
`REASON_GROUP_REFERENCE_AMBIGUOUS`	Multiple groups share the same name. Use a group ID instead.
`REASON_SITE_NOT_FOUND`	The site could not be found in the organization.
`REASON_SITE_DUPLICATE_ENTRY`	The same site was listed more than once for this user.
`REASON_SITE_CANNOT_ASSIGN_TO_DEACTIVATED_USER`	Sites cannot be assigned to users who are deactivated or will be deactivated.
`REASON_USER_ALREADY_ASSIGNED_TO_ANCESTOR_SITE`	The user is already assigned to a higher-level site. For example, this happens if a user is assigned to a site under a parent country they belong to.
`REASON_SITE_INVALID_REMOVE_REFERENCE`	The site reference specified for removal is invalid.
`REASON_SITE_ASSOCIATION_LIMIT_REACHED`	The maximum number of site associations for this user has been reached.
`REASON_SITE_REFERENCE_AMBIGUOUS`	Multiple sites share the same name. Use a site ID instead.
`REASON_USER_ATTRIBUTE_DISABLED`	The user attribute is currently disabled and cannot be used.
`REASON_LAST_ADMINISTRATOR`	The requested change would remove the organization's last administrator, which is not allowed.
`REASON_FIELD_VALUE_INVALID_MIN_LENGTH`	The value is shorter than the minimum allowed length.
`REASON_FIELD_VALUE_INVALID_MAX_LENGTH`	The value exceeds the maximum allowed length.
`REASON_COMPANY_NOT_FOUND`	The company could not be found in the organization.
`REASON_COMPANY_DUPLICATE_ENTRY`	The same company was listed more than once for this user.
`REASON_COMPANY_CANNOT_ASSIGN_TO_DEACTIVATED_USER`	Companies cannot be assigned to users who are deactivated or will be deactivated.
`REASON_COMPANY_INVALID_REMOVE_REFERENCE`	The company reference specified for removal is invalid.
`REASON_COMPANY_MEMBERSHIP_CHANGE_NOT_ALLOWED_FOR_CALLER`	You don't have permission to change user membership for this company.