Troubleshoot the Team API

Applies to: Team API

Troubleshoot errors you might encounter when using the Team API.

Link to section

Overview

The Team API uses the standard set of Square error codes to communicate API operation errors. The following sections provide details about the request state that returns errors.

Link to section

Create a team member

The Square error response says that the request is a BAD_REQUEST.

Link to section

Cause

Any of the following error conditions might apply:

Link to section

Update a team member

The Square error response says that the request is a BAD_REQUEST.

Link to section

Cause

Any of the following error conditions might apply:

  • The request body is clearing required fields.
  • The request body phone_number and email_address values aren't in a valid format.
  • Updating email_address when a team member has already linked their Square account. This is because a team member's Square account email cannot be changed.
  • Updating email_address use the email address of a different team member. A given email address can only be registered to a single team member.
Link to section

Missing compliance required fields - Canada only

To comply with regulatory requirements, sellers operating in Canada must record the address and date of birth (DOB) of team members when assigning permissions in the Square Dashboard.

Starting April 22, 2024, Square enforces these requirements if the seller:

  • Didn't specify their business as Individual/Sole Proprietor.
  • Created a Square account after April 27, 2022.

Attempts by applications to update team members that don't have a DOB and address return BAD_REQUEST errors with the following details:

  • Missing compliance required field: birth_date
  • Missing compliance required field: address

Any updates to these team members must be made by the seller in the Team members section of the Square Dashboard.

Link to section

Retrieve a team member

The Square error response says that the request is a BAD_REQUEST.

Link to section

Cause

A team member with the specified ID isn't found.

Make sure that the team_member_id provided in the request is the Square-assigned ID, which is represented by the id field in the TeamMember object. Retrieving a team member using the ID assigned by sellers in the Square Dashboard (represented by the reference_id field) isn't supported.

Link to section

Create or update a wage setting

The Square error response says that the request is a BAD_REQUEST or an UNPROCESSABLE_ENTITY.

Link to section

BAD_REQUEST

Any of the following error conditions might apply:

Link to section

UNPROCESSABLE_ENTITY

Any of the following error conditions might apply:

  • Invalid JobAssignment objects are included in job_assignments. Common invalid job assignments include:

  • There is no active Team Plus subscription with the Square account and job_assignments in the request body contains more than one job assignment.

    Subscribe to activate a Team Plus subscription to be able to add multiple wages for a team member in the Square Dashboard:

    1. Open the Team page in the Square Dashboard.

    2. Choose the team member who you want to have multiple wages.

      A graphic showing where to add team member permissions in the Seller Dashboard Team management application.

    3. In the team member window, choose ... to open a menu of more edit options.

    4. Choose Edit Compensation.

      A graphic showing where to set a team member job title in the Seller Dashboard Team management application.

    5. Choose Sign up for Team Plus to add another wage.

Link to section

Bulk create team members

An attempt to create TeamMember objects can result in a BAD_REQUEST error when:

Link to section

Bulk update team members

An attempt to update TeamMember objects can result in a BAD_REQUEST error when:

  • Clearing required fields.
  • The phone_number and email_address values aren't in a valid format.
  • Updating email_address when a team member has already linked their Square account. This is because a team member's Square account email cannot be changed.