Error Codes

HTTP Status Meaning
200 - OK Everything worked as expected
400 - Bad Request The request was unacceptable, often due to a missing or incorrect required parameter
401 - Unauthorized No valid API Key provided
402 - Request Failed The parameters were valid but the request failed
403 - Forbidden The API key doesn't have permission to perform the request
404 - Not Found The requested resource doesn't exist
409 - Conflict The request conflicts with another request
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500, 502, 503, 504 - Server Errors Something went wrong on Zeal's end

Zeal API error messages are returned in JSON format.

Example Error Response

{
  "success": false,
  "errors": [\
    {\
      "message": "Employee does not exist",\
      "code": 30\
    }\
  ]
}
Error Code Message Description
0 This 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 support@zeal.com to gain access.
1 No Authorization Header Corresponds with HTTP 400
No authorization header or Bearer Token was found in the request
2 No companyID in the request query Corresponds with HTTP 400
No companyID was found in the query of request when expected.
3 No companyID in the request body Corresponds with HTTP 400
No companyID was found in the body of the request when expected.
4 No user with this companyID exists Corresponds with HTTP 400
No user with the given companyID exists.
6 No partnerID in the body or query of request Corresponds with HTTP 400
No partnerID was found in the body or query of the request when expected
7 No Zeal Partner with this partnerID exists Corresponds with HTTP 400
No Zeal Partner with the given partner ID exists.
8 Error with Key Corresponds with HTTP 401
Given API key does not exist for Zeal partner with given partnerID
9 Invalid format for the time given in the query Corresponds with HTTP 400
The format of the time parameter for the request does not adhere to the ISO-8601 format.
10 Reporting Period with this ID does not exist Corresponds with HTTP 400
No Reporting Period with this ID exists.
11 No 'shifts' array found in the body of the request Corresponds with HTTP 400
12 Worker(s) with given employeeID(s) in the body of the request does not exist Corresponds with HTTP 400
13 Object(s) is missing required fields or have improperly formatted data Corresponds with HTTP 400.
Consult API reference for proper formatting.
14 Shift(s) with given shiftID(s) is not found for this user Corresponds with HTTP 404
This could have occurred because of an improperly formatted shiftID.
16 No employeeCheckID found in the query of the request Corresponds with HTTP 400
17 Object with this ID does not exist Corresponds with HTTP 400
18 No end date found in the query of the request Corresponds with HTTP 400
19 No start date found in the query of the request Corresponds with HTTP 400
20 Dates provided in the query of request are invalid/inappropriately formatted Corresponds with HTTP 400. Please format dates as YYYY-MM-DD
21 End Date occurs before Start Date Corresponds with HTTP 400
22 No 'employees' array found in the body of the request Corresponds with HTTP 400
23 Employee with this employeeID does not exist Corresponds with HTTP 400
24 Zeal Partner does not have access to this company's information Corresponds with HTTP 400
25 This is only a Live Mode feature. Test Key does not have permission to perform this request Corresponds with HTTP 403.
26 No shiftID in the query of request Corresponds with HTTP 400
27 No 'new_employees' array found in the body of the request Corresponds with HTTP 400
28 Employee object(s) are missing the required fields. Corresponds with HTTP 400
29 Worker(s) with given email(s) already exist. Please try again Corresponds with HTTP 404
30 Employee is already onboarded/on leave/terminated Corresponds with HTTP 404
31 No Pending Employee Check exists within the given employeeCheckID Corresponds with HTTP 404
32 Employee Check for this employee and check date already exists. Error object will include an employeeID and check date Corresponds with HTTP 400
33 This employee is working in a state for which a State Payroll Tax Number has not been submitted. This error only applies in Live Mode Corresponds with HTTP 400
34 The 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
35 No contractorID in the body/query of the request Corresponds with HTTP 400
36 Object(s) does not have a bank account Corresponds with HTTP 400
37 Cannot onboard employee: missing property Corresponds with HTTP 400
38 Employee is already onboarded Corresponds with HTTP 400
39 Internal Server Error Corresponds with 500. Message will relay actual server error.
40 CompanyID mismatch in body and query of request Corresponds with HTTP 400
41 Key is not authorized to perform this request Corresponds with HTTP 403
42 No contractorID or employeeID in the body/query of the request Corresponds with HTTP 400
43 Employee Check with this check ID does not exist Corresponds with HTTP 400
44 Date is not a valid date Corresponds with HTTP 400
45 Date must not be in the past Corresponds with HTTP 400
46 Contractor Payment with this payment ID does not exist Contractor Payment with this payment ID does not exist
47 Validation Error Corresponds with HTTP 403
48 The address provided is not a valid, mail-deliverable address Corresponds with HTTP 400
49 Company must be live Corresponds with HTTP 403
50 Must provide a valid companyID Corresponds with HTTP 400
51 No company with this companyID exists Corresponds with HTTP 404
52 No document with this document ID exists Corresponds with HTTP 404
53 No document of this type within the given scope exists Corresponds with HTTP 404
54 No document with this jurisdiction and company ID has been submitted Corresponds with HTTP 404
55 Shifts with negative wages not currently supported Corresponds with HTTP 400
56 Routing number is invalid Corresponds with HTTP 400
57 Employee or contractor has not finished onboarding Corresponds with HTTP 400
58 Work Location(s) not found Corresponds with HTTP 400
59 Failed to update/upsert Work Location Corresponds with HTTP 400
60 Failed to create Work Location Corresponds with HTTP 400
61 Another employee in this company already has the same SSN Corresponds with HTTP 400
62 Create employees payload contains duplicate SSNs Corresponds with HTTP 400
63 SSN must be an optional property or of type string Corresponds with HTTP 400
64 Request is not of the expected shape Corresponds with HTTP 400
65 Maximum number of allowed checks exceeded Corresponds with HTTP 400
66 Only pending checks can be previewed. Received non-pending check(s) Corresponds with HTTP 400
67 No workLocationID in the body of the request Corresponds with HTTP 400
68 Bank Account with this employeeID or contractorID does not exist Corresponds with HTTP 400
69 Another employee in this company already has the same external ID Corresponds with HTTP 400
70 Another contractor in this company already has the same external ID Corresponds with HTTP 400
71 No W-4 exists for this jurisdiction Corresponds with HTTP 400
72 Employee or Contractor ID is not formatted correctly Corresponds with HTTP 400
73 Contractor with this contractorID does not exist Corresponds with HTTP 400
74 Invalid check date Corresponds with HTTP 400
75 Must be valid SSN format - eg. XXXYYZZZZ Corresponds with HTTP 400
76 Another contractor in this company already has the same SSN Corresponds with HTTP 409
77 Start date cannot be after end date Corresponds with HTTP 400
78 Email already exists Corresponds with HTTP 409
79 Migration failed Corresponds with HTTP 400
80 Please provide a file to upload Corresponds with HTTP 400
81 Contractor Payment for this contractor and pay date already exists. Error object will include a contractorID and pay_date Corresponds with HTTP 400
82 CompanyID was not found Corresponds with HTTP 400
83 Failed to retrieve Partner Information by ID Corresponds with HTTP 400
84 Email or password is incorrect Corresponds with HTTP 401
85 Partner not found Corresponds with HTTP 400
86 Either document ID or type, jurisdiction, and scope are required Corresponds with HTTP 400
87 Employee has missing or invalid residency Corresponds with HTTP 422
88 Contractor is already onboarded Corresponds with HTTP 400
89 The 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 resubmit Corresponds with HTTP 400
90 Only able to regenerate requirement for state-scoped requirements Corresponds with HTTP 400
91 Invalid tax parameter jurisdiction Corresponds with HTTP 400
92 Invalid tax requirement ID Corresponds with HTTP 400
93 Invalid tax parameter value Corresponds with HTTP 400
94 Employee's default wage has not been set so please provide an appropriate wage in the shifts object(s) Corresponds with HTTP 400
95 The requested feature is disabled Corresponds with HTTP 403
96 Value must be positive Corresponds with HTTP 400
97 Email must be valid Corresponds with HTTP 400
98 This account does not have access to this endpoint Corresponds with HTTP 403
99 This employee is not onboarded Corresponds with HTTP 400
100 This employee is on leave/terminated Corresponds with HTTP 400
101 Forbidden Corresponds with HTTP 403
102 You must create between 1 and 100 checks Corresponds with HTTP 400
103 Unauthorized Corresponds with HTTP 401
104 Provided deduction template id(s) not found under companyID Corresponds with HTTP 404
105 Parameter is expected to be of type objectid string Corresponds with HTTP 400
106 Net pay negative - this check will fail Corresponds with HTTP 422
107 Bad Form Data Corresponds with HTTP 422
108 Provided check is invalid Corresponds with HTTP 400
109 Accrual policy with this policy code not found Corresponds with HTTP 404
110 Historical shift would be modified by overtime calculation Corresponds with HTTP 422
111 Value for earning type must be less than 0 Corresponds with HTTP 400
112 Value must be negative Corresponds with HTTP 400
113 Jurisdiction does not exist Corresponds with HTTP 404
114 Company not setup for regular payroll Corresponds with HTTP 400
115 Account not found Corresponds with HTTP 404
116 Value must be a decimal Corresponds with HTTP 400