Troubleshoot the Team API

This topic helps you troubleshoot errors with Team API operations by providing the error conditions for each error code you might encounter.

The Team API uses the standard set of Square error codes to communicate API operation errors. This topic gives 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:

• Required fields are empty.

• The phone_number and email_address values aren't in a valid format.

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

Retrieve a team member

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

Link to section

Cause

The team member ID isn't found.

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:

• job_assignments isn't included in the request.

• job_assignments is an empty array.

• job_assignments contains more than 12 job assignments.

• version is supplied but doesn't match the server version.

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:

  • pay_type is HOURLY and hourly_rate isn't supplied.

  • pay_type is HOURLY and annual_rate or weekly_hours is supplied.

  • pay_type is SALARY and annual_rate or weekly_hours isn't supplied.

  • pay_type is SALARY and hourly_rate is supplied but the amount doesn't match the product of hourly_rate multiplied by weekly_hours.

  • pay_type is NONE and hourly_rate, annual_rate, or weekly_hours is supplied.

  • The amount of annual_rate or hourly_rate is negative.

  • The currency of annual_rate or hourly_rate does match the currency of the Square account.

  • job_title is duplicated.

• 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 Seller Dashboard:

  1. Open the Team page in the Seller Dashboard.

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

     

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

  4. Choose Edit Compensation.

     

  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:

• Required fields are empty.

• The phone_number and email_address values aren't in a valid format.

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.