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. |
Updated about 2 months ago