Error Codes

All Zeal responses follow HTTP Status Codes.

HTTP StatusMeaning
200 - OKEverything worked as expected
400 - Bad RequestThe request was unacceptable, often due to a missing or incorrect required parameter
401 - UnauthorizedNo valid API Key provided
402 - Request FailedThe parameters were valid but the request failed
403 - ForbiddenThe API key doesn't have permissions to perform the request
404 - Not FoundThe requested resource doesn't exist
409 - ConflictThe request conflicts with another request
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests
500,502,503,504 - Server ErrorsSomething went wrong on Zeal's end

Zeal API error messages are returned in JSON format.

{
   "success": false,
   "errors": [
      {"message":"Employee does not exist", "code":30}
   ]
}
Error CodeMessageDescription
0This account does not have access to live payroll. You may only use Test Keys/Test Mode for now.Corresponds with HTTP 403

The account does not have access to live payroll yet. Please contact [email protected] to gain access.
1No Authorization HeaderCorresponds with HTTP 400

No authorization header or Bearer Token was found in request
2No companyID in the request queryCorresponds with HTTP 400

No companyID was found in query of request when expected.
3No companyID in the request bodyCorresponds with HTTP 400

No companyID was found in the body of the request when expected.
4No user with this companyID exists.Corresponds with HTTP 400

No user with the given companyID exists.
5Error with key.Corresponds with HTTP 401

Given API key does not exist for user with given companyID
6No partnerID in body or query of requestCorresponds with HTTP 400

No partnerID was found in the body or query of request when expected
7No Zeal Partner with this partnerID existsCorresponds with HTTP 400

No Zeal Partner with the given partner ID exists.
8Error with KeyCorresponds with HTTP 401

Given API key does not exist for Zeal partner with given partnerID
9Invalid format for time given in queryCorresponds with HTTP 400

The format of the time parameter for the request does not adhere to ISO-8601 format.
10Reporting Period with this ID does not existCorresponds with HTTP 400

No Reporting Period with this ID exists.
11No 'shifts' array found in the body of the requestCorresponds with HTTP 400
12Worker(s) with given employeeID(s) in the body of the request does not existCorresponds with HTTP 400
13Object(s) is missing required fields or has improperly formatted dataCorresponds with HTTP 400.
Consult API reference for proper formatting.
14Shift(s) have been assigned wages below minimum wageCorresponds with HTTP 400

*Please pay employees over minimum wage.
15Shift(s) with given shiftID(s) is not found for this userCorresponds with HTTP 404

This could have occurred because of an improperly formatted shiftID.
16No employeeCheckID found in the query of requestCorresponds with HTTP 400
17Object with this ID does not existCorresponds with HTTP 400
18No end date found in query of requestCorresponds with HTTP 400
19No start date found in query of requestCorresponds with HTTP 400
20Dates provided in query of request are invalid/inappropriately formattedCorresponds with HTTP 400. Please format dates as YYYY-MM-DD
21End Date occurs before Start DateCorresponds with HTTP 400
22No 'employees' array found in the body of requestCorresponds with HTTP 400
23Employee with this employeeID does not existCorresponds with HTTP 400
24Zeal Partner does not have access to this company's informationCorresponds with HTTP 400
25This is only a Live Mode feature. Test Key does not have permission to perform this request.Corresponds with HTTP 403.
26No shiftID in the query of requestCorresponds with HTTP 400
27No 'new_employees' array found in the body of the requestCorresponds with HTTP 400
28Employee object(s) are missing the required fields.Corresponds with HTTP 400
29Worker(s) with given email(s) already exist. Please try againCorresponds with HTTP 404
30Employee is already onboarded/on leave/terminatedCorresponds with HTTP 404
31No Pending Employee Check exists within the given employeeCheckIDCorresponds with HTTP 404
32Employee Check for this employee and check date already exists. Error object will include an employeeID and check dateCorresponds with HTTP 400
33This employee is working in a state for which a State Payroll Tax Number has not been submitted. This error only applies in Live ModeCorresponds with HTTP 400
34The address provided is not suitable for taxation. Address fields where wholly invalid or resolved to a taxable location with is_suitable_for_taxation equal to false. Use the Resolve Taxable Location endpoint for more details.Corresponds with HTTP 400
35No contractorID in the body/query of the requestCorresponds with HTTP 400
36Object(s) does not have a bank accountCorresponds with HTTP 400
37Cannot onboard employee: missing propertyCorresponds with HTTP 400
38Employee is already onboardedCorresponds with HTTP 400
39Internal Server ErrorCorresponds with 500. Message will relay actual server error.
40CompanyID mismatch in body and query of requestCorresponds with HTTP 400
41Key is not authorized to perform this requestCorresponds with HTTP 403
42No contractorID or employeeID in the body/query of requestCorresponds with HTTP 400
43Employee Check with this check ID does not existCorresponds with HTTP 400
44Date is not a valid dateCorresponds with HTTP 400
45Date must not be in the pastCorresponds with HTTP 400
46Contractor Payment with this payment ID does not existContractor Payment with this payment ID does not exist
47Validation ErrorCorresponds with HTTP 403
48The address provided is not a valid, mail deliverable addressCorresponds with HTTP 400
49Company must be liveCorresponds with HTTP 403
50Must provide a valid companyIDCorresponds with HTTP 400
51No company with this companyID existsCorresponds with HTTP 404
52No document with this document ID existsCorresponds with HTTP 404
53No document of this type within the given scope existsCorresponds with HTTP 404
54No document with this jurisdiction and company ID have been submitted.Corresponds with HTTP 404
55Shifts with negative wages not currently supportedCorresponds with HTTP 400
56Routing number is invalidCorresponds with HTTP 400
57Employee or contractor has not finished onboardingCorresponds with HTTP 400
58Work Location(s) not foundCorresponds with HTTP 400
59Failed to update/upsert Work LocationCorresponds with HTTP 400
60Failed to create Work LocationCorresponds with HTTP 400
61Another employee in this company already has the same SSNCorresponds with HTTP 400
62Create employees payload contains duplicate SSNsCorresponds with HTTP 400
63SSN must be an optional property or of type stringCorresponds with HTTP 400
64Request is not of the expected shapeCorresponds with HTTP 400
65Maximum number allowed checks exceededCorresponds with HTTP 400
66Only pending checks can be previewed. Received non pending check(s)Corresponds with HTTP 400
67No workLocationID in the body of requestCorresponds with HTTP 400
68Bank Account with this employeeID or contractorID does not existCorresponds with HTTP 400
69Another employee in this company already has the same external IDCorresponds with HTTP 400
70Another contractor in this company already has the same external IDCorresponds with HTTP 400
71No W-4 exists for this jurisdictionCorresponds with HTTP 400
72Employee or Contractor ID is not formatted correctlyCorresponds with HTTP 400
73Contractor with this contractorID does not existCorresponds with HTTP 400
74Invalid check dateCorresponds with HTTP 400
75Must be valid SSN format - eg. XXXYYZZZZCorresponds with HTTP 400
76Another contractor in this company already has the same SSNCorresponds with HTTP 409
77Start cannot be before end dateCorresponds with HTTP 400
78Email already existsCorresponds with HTTP 409
79Migration failedCorresponds with HTTP 400
80Please provide a file to uploadCorresponds with HTTP 400
81Contractor Payment for this contractor and pay date already exists. Error object will include a contractorID and pay_date.Corresponds with HTTP 400
82CompanyID was not foundCorresponds with HTTP 400
83Failed to retrieve White Label Information by IDCorresponds with HTTP 400
84Email or password is incorrectCorresponds with HTTP 401
85White Label not foundCorresponds with HTTP 400
86Either document ID or type, jurisdiction, and scope are requiredCorresponds with HTTP 400
87Employee has missing or invalid residencyCorresponds with HTTP 422
88Contractor is already onboardedCorresponds with HTTP 400
89The given date is on a weekend/bank holiday or the current time is after 2 PM two days before the given date. Please correct the date and resubmitCorresponds with HTTP 400
90Only able to regenerate requirement for state scoped requirementsCorresponds with HTTP 400
91Invalid tax parameter jurisdictionCorresponds with HTTP 400
92Invalid tax requirement IDCorresponds with HTTP 400
93Invalid tax parameter valueCorresponds with HTTP 400
94Employee's default wage has not been set so please provide an appropriate wage in the shifts object(s)Corresponds with HTTP 400
95The requested feature is disabledCorresponds with HTTP 403