Payroll Blockers

If there is a payroll blocker throughout the process, you will receive a payroll_blocker category 422 error. You will be able to get the reason for the error using the metadata.

{
  "errors": [
    {
      "error_key": "base",
      "category": "payroll_blocker",
      "message": "Company or employee address could not be verified. Please ensure all addresses are valid.",
      "metadata": {
        "key": "geocode_error"
      }
    }
  ]
}

You can also view the payroll blockers for a given company using the GET companies/{company_uuid}/payrolls/blockers endpoint.

curl --request GET \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/blockers \
     --header 'X-Gusto-API-Version: 2023-02-01' \
     --header 'accept: application/json'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/company_uuid/payrolls/blockers';
const options = {method: 'GET', headers: {accept: 'application/json'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Below is a list of all possible metadata key values and how to resolve them.

Key	Message	How to Resolve
`eftps_in_error`	We could not make payments to the Electronic Federal Tax Payment System.	Please contact support.
`geocode_error`	Company or employee address could not be verified. Please ensure all addresses are valid.	Confirm the company and employee addresses are all valid.
`geocode_needed`	Company or employee address verification is missing. Please ensure all addresses are entered correctly.	Confirm the company and employee addresses are completed.
`invalid_signatory`	A signatory who is authorized to sign documents on behalf of your company is required. Please ensure their identity verification is successful.	Use the `GET companies/{company_uuid}/signatories` endpoint to check the `identity_verification_status`.
`needs_approval`	Company needs to be approved to run payroll.	We are reviewing the company onboarding information, wait for the `companny.approved` webhook to continue.
`needs_onboarding`	Company must complete all onboarding requirements in order to run payroll.	Use the `GET companies/{company_uuid}/onboarding_status` endpoint and confirm all required steps are completed.
`pay_schedule_setup_not_complete`	Some employees don’t have a pay schedule set up yet. Please complete this step to run payroll.	Verify that all employees have a pay schedule.
`soft_suspended`	Company is placed in a "soft" suspension state and requires missing/incorrect information to be corrected.	Company is placed in a "soft" suspension state and requires missing/incorrect information to be corrected. Validate the state tax information is completed and correct. If state tax information is correct, please contact support.
`suspended`	Company is suspended and cannot run payroll.	Please contact support if you believe this is an error.
`wc_pending_approval`	Worker's compensation policy needs to be accepted.	The worker’s compensation process has not been completed and may require more information. Please contact support.
`pending_payroll_review`	Payroll is blocked. We are reviewing payroll information in your account. Please contact support if you believe this is an error.	Please contact support if you believe this is an error.